Centralize documentation in the source repository (#124)

Co-authored-by: Maximilien <[email protected]>

src/batch-doctrine-persistence/docs/object-registry.md → docs/batch-doctrine-persistence/object-registry.md

@@ -78,4 +78,4 @@ Otherwise, the query will be the fastest possible because it will use the object
 
 ## On the same subject
 
-- [What is an item job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/item-job.md)
+- [What is an item job ?](../batch/domain/item-job.md)

src/batch-openspout/docs/flat-file-item-reader.md → docs/batch-openspout/flat-file-item-reader.md

@@ -1,6 +1,6 @@
 # Item reader with CSV/ODS/XLSX files
 
-The [FlatFileReader](../src/Reader/FlatFileReader.php) is a reader 
+The [FlatFileReader](../../src/batch-openspout/src/Reader/FlatFileReader.php) is a reader 
 that will read from CSV/ODS/XLSX file and return each line as an array.
 
 ```php
@@ -45,4 +45,4 @@ new FlatFileReader(
 
 ## On the same subject
 
-- [What is an item reader ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/item-job/item-reader.md)
+- [What is an item reader ?](../batch/domain/item-job/item-reader.md)

src/batch-openspout/docs/flat-file-item-writer.md → docs/batch-openspout/flat-file-item-writer.md

@@ -1,6 +1,6 @@
 # Item writer with CSV/ODS/XLSX files
 
-The [FlatFileWriter](../src/Writer/FlatFileWriter.php) is a writer that will write to CSV/ODS/XLSX file and each item will
+The [FlatFileWriter](../../src/batch-openspout/src/Writer/FlatFileWriter.php) is a writer that will write to CSV/ODS/XLSX file and each item will
 written its own line.
 
 ```php
@@ -47,4 +47,4 @@ new FlatFileWriter(
 
 ## On the same subject
 
-- [What is an item writer ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/item-job/item-writer.md)
+- [What is an item writer ?](../batch/domain/item-job/item-writer.md)

src/batch-symfony-console/docs/command.md → docs/batch-symfony-console/command.md

@@ -1,6 +1,6 @@
 # Command
 
-The [RunJobCommand](../src/RunJobCommand.php) can execute any job.
+The [RunJobCommand](../../src/batch-symfony-console/src/RunJobCommand.php) can execute any job.
 
 The command accepts 2 arguments :
 - the job name to execute

src/batch-symfony-console/docs/job-launcher.md → docs/batch-symfony-console/job-launcher.md

@@ -1,6 +1,6 @@
 # Job launcher
 
-The [RunCommandJobLauncher](../src/RunCommandJobLauncher.php) execute jobs via an asynchronous symfony command.
+The [RunCommandJobLauncher](../../src/batch-symfony-console/src/RunCommandJobLauncher.php) execute jobs via an asynchronous symfony command.
 
 The command called is [`yokai:batch:run`](command.md), and the command will actually execute the job.
 
@@ -9,4 +9,4 @@ Additionally, the command will run with an output redirect (`>>`) to `var/log/ba
 
 ## On the same subject
 
-- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)
+- [What is a job launcher ?](../batch/domain/job-launcher.md)

src/batch-symfony-framework/docs/getting-started.md → docs/batch-symfony-framework/getting-started.md

@@ -24,7 +24,7 @@ yokai_batch:
           async: ...
 ```
 
-> **note**: if you do not configure anything here, you will be using the [`SimpleJobLauncher`](https://github.com/yokai-php/batch/blob/0.x/src/Launcher/SimpleJobLauncher.php).
+> **note**: if you do not configure anything here, you will be using the [`SimpleJobLauncher`](../../src/batch/src/Launcher/SimpleJobLauncher.php).
 
 The `default` job launcher, must reference a launcher name, defined in the `launchers` list.
 The `default` job launcher will be the autowired instance of job launcher when you ask for one.
@@ -48,9 +48,9 @@ final class YourAppCode
 ```
 
 All `launchers` are configured using a DSN, every scheme has it's own associated factory.
-- `simple://simple`: a [`SimpleJobLauncher`](https://github.com/yokai-php/batch/blob/0.x/src/Launcher/SimpleJobLauncher.php), no configuration allowed
-- `messenger://messenger`: a [`DispatchMessageJobLauncher`](https://github.com/yokai-php/batch-symfony-messenger/blob/0.x/src/DispatchMessageJobLauncher.php), no configuration allowed
-- `console://console`: a [`RunCommandJobLauncher`](https://github.com/yokai-php/batch-symfony-console/blob/0.x/src/RunCommandJobLauncher.php), configurable options:
+- `simple://simple`: a [`SimpleJobLauncher`](../../src/batch/src/Launcher/SimpleJobLauncher.php), no configuration allowed
+- `messenger://messenger`: a [`DispatchMessageJobLauncher`](../../src/batch-symfony-messenger/src/DispatchMessageJobLauncher.php), no configuration allowed
+- `console://console`: a [`RunCommandJobLauncher`](../../src/batch-symfony-console/src/RunCommandJobLauncher.php), configurable options:
   - `log`: the filename where command output will be redirected (defaults to `batch_execute.log`)
 - `service://service`: pointing to a service of your choice, configurable options:
   - `service`: the id of the service to use (required, an exception will be thrown otherwise)
@@ -122,7 +122,7 @@ final class NameOfYourJob implements JobInterface, JobWithStaticNameInterface
 ```
 
 > **note**: when registering jobs with dedicated class, you can use the
-> [JobWithStaticNameInterface](../src/JobWithStaticNameInterface.php) interface
+> [JobWithStaticNameInterface](../../src/batch-symfony-framework/src/JobWithStaticNameInterface.php) interface
 > to be able to specify the job name of your service.
 > Otherwise, the service id will be used, and in that case, the service id is the FQCN.
 
@@ -183,6 +183,6 @@ final readonly class YourService
 
 ## On the same subject
 
-- [What is a job execution storage ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-execution-storage.md)
-- [What is a job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job.md)
-- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)
+- [What is a job execution storage ?](../batch/domain/job-execution-storage.md)
+- [What is a job ?](../batch/domain/job.md)
+- [What is a job launcher ?](../batch/domain/job-launcher.md)

src/batch-symfony-framework/docs/ui.md → docs/batch-symfony-framework/ui.md

@@ -32,7 +32,7 @@ _yokai_batch:
 
 ### Templating
 
-The templating service is used by the [JobController](../src/UserInterface/Controller/JobController.php) to render its templates.
+The templating service is used by the [JobController](../../src/batch-symfony-framework/src/UserInterface/Controller/JobController.php) to render its templates.
 It's a wrapper around [Twig](https://twig.symfony.com/), for you to control templates used, and variables passed.
 
 > By default
@@ -191,6 +191,6 @@ But you can also register job name dedicated templates if you need some specific
 
 ## On the same subject
 
-- [What is a job execution storage ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-execution-storage.md)
-- [What is a job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job.md)
-- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)
+- [What is a job execution storage ?](../batch/domain/job-execution-storage.md)
+- [What is a job ?](../batch/domain/job.md)
+- [What is a job launcher ?](../batch/domain/job-launcher.md)

src/batch-symfony-messenger/docs/job-launcher.md → docs/batch-symfony-messenger/job-launcher.md

@@ -1,10 +1,10 @@
 # Job launcher
 
-The [DispatchMessageJobLauncher](../src/DispatchMessageJobLauncher.php) execute 
+The [DispatchMessageJobLauncher](../../src/batch-symfony-messenger/src/DispatchMessageJobLauncher.php) execute 
 jobs via a symfony command message dispatch.
 
-A [LaunchJobMessage](../src/LaunchJobMessage.php) message will be dispatched
-and handled by the [LaunchJobMessageHandler](../src/LaunchJobMessageHandler.php) 
+A [LaunchJobMessage](../../src/batch-symfony-messenger/src/LaunchJobMessage.php) message will be dispatched
+and handled by the [LaunchJobMessageHandler](../../src/batch-symfony-messenger/src/LaunchJobMessageHandler.php) 
 will be called with that message after being routed.
 
 ## How to configure an async transport for the launcher ?
@@ -29,4 +29,4 @@ framework:
 
 ## On the same subject
 
-- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)
+- [What is a job launcher ?](../batch/domain/job-launcher.md)

docs/batch/domain/item-job/item-processor.md

@@ -0,0 +1,37 @@
+# What is an item processor ?
+
+The item processor is used by the item job to transform every read item.
+
+It can be any class implementing [ItemProcessorInterface](../../../../src/batch/src/Job/Item/ItemProcessorInterface.php).
+
+## What types of item processors exists ?
+
+**Built-in item processors:**
+- [ArrayMapProcessor](../../../../src/batch/src/Job/Item/Processor/ArrayMapProcessor.php):
+  apply a callback to each element of array items.
+- [CallbackProcessor](../../../../src/batch/src/Job/Item/Processor/CallbackProcessor.php):
+  use a callback to transform each items.
+- [ChainProcessor](../../../../src/batch/src/Job/Item/Processor/ChainProcessor.php):
+  chain transformation of multiple item processor, one after the other.
+- [FilterUniqueProcessor](../../../../src/batch/src/Job/Item/Processor/FilterUniqueProcessor.php):
+  assign an identifier to each item, and skip already encountered items.
+- [NullProcessor](../../../../src/batch/src/Job/Item/Processor/NullProcessor.php):
+  perform no transformation on items.
+- [RoutingProcessor](../../../../src/batch/src/Job/Item/Processor/RoutingProcessor.php):
+  route processing to different processor based on your logic.
+
+**Item processors from bridges:**
+- [SkipInvalidItemProcessor (`symfony/validator`)](../../../../src/batch-symfony-validator/src/SkipInvalidItemProcessor.php):
+  validate item and throw exception if invalid that will cause item to be skipped.
+- [DenormalizeItemProcessor (`symfony/serializer`)](../../../../src/batch-symfony-serializer/src/DenormalizeItemProcessor.php):
+  denormalize each item.
+- [NormalizeItemProcessor (`symfony/serializer`)](../../../../src/batch-symfony-serializer/src/NormalizeItemProcessor.php):
+  normalize each item.
+
+**Item processors for testing purpose:**
+- [TestDebugProcessor](../../../../src/batch/src/Test/Job/Item/Processor/TestDebugProcessor.php):
+  dummy item processor that you can use in your unit tests.
+
+## On the same subject
+
+- [What is an item job ?](../item-job.md)

docs/batch/domain/item-job/item-reader.md

@@ -0,0 +1,43 @@
+# What is an item reader ?
+
+The item reader is used by the item job to extract item from a source.
+
+It can be any class implementing [ItemReaderInterface](../../../../src/batch/src/Job/Item/ItemReaderInterface.php).
+
+## What types of item readers exists ?
+
+**Built-in item readers:**
+- [FixedColumnSizeFileReader](../../../../src/batch/src/Job/Item/Reader/Filesystem/FixedColumnSizeFileReader.php):
+  read a file line by line, and decode each line with fixed columns size to an array.
+- [JsonLinesReader](../../../../src/batch/src/Job/Item/Reader/Filesystem/JsonLinesReader.php):
+  read a file line by line, and decode each line as JSON.
+- [AddMetadataReader](../../../../src/batch/src/Job/Item/Reader/AddMetadataReader.php):
+  decorates another reader by adding static information to each read item.
+- [IndexWithReader](../../../../src/batch/src/Job/Item/Reader/IndexWithReader.php):
+  decorates another reader by changing index of each item.
+- [ParameterAccessorReader](../../../../src/batch/src/Job/Item/Reader/ParameterAccessorReader.php):
+  read from an inmemory value located at some configurable place.
+- [SequenceReader](../../../../src/batch/src/Job/Item/Reader/SequenceReader.php):
+  read from multiple item reader, one after the other.
+- [StaticIterableReader](../../../../src/batch/src/Job/Item/Reader/StaticIterableReader.php):
+  read from an iterable you provide during construction.
+- [CallbackReader](../../../../src/batch/src/Job/Item/Reader/CallbackReader.php):
+  read from a `Closure` you provide during construction.
+
+**Item readers from bridges:**
+- [FlatFileReader (`openspout/openspout`)](../../../../src/batch-openspout/src/Reader/FlatFileReader.php):
+  read from any CSV/ODS/XLSX file.
+- [DoctrineDBALQueryOffsetReader (`doctrine/dbal`)](../../../../src/batch-doctrine-dbal/src/DoctrineDBALQueryOffsetReader.php):
+  read execute an SQL query and iterate over results, using a limit + offset pagination strategy.
+- [DoctrineDBALQueryCursorReader (`doctrine/dbal`)](../../../../src/batch-doctrine-dbal/src/DoctrineDBALQueryCursorReader.php):
+  read execute an SQL query and iterate over results, using a column based cursor strategy.
+- [EntityReader (`doctrine/orm`)](../../../../src/batch-doctrine-orm/src/EntityReader.php):
+  read from any Doctrine ORM entity.
+
+**Item readers for testing purpose:**
+- [TestDebugReader](../../../../src/batch/src/Test/Job/Item/Reader/TestDebugReader.php):
+  dummy item reader that you can use in your unit tests.
+
+## On the same subject
+
+- [What is an item job ?](../item-job.md)

docs/batch/domain/item-job/item-writer.md

@@ -0,0 +1,53 @@
+# What is an item writer ?
+
+The item writer is used by the item job to load every processed item.
+
+It can be any class implementing [ItemWriterInterface](../../../../src/batch/src/Job/Item/ItemWriterInterface.php).
+
+## What types of item writers exists ?
+
+**Built-in item writers:**
+- [JsonLinesWriter](../../../../src/batch/src/Job/Item/Writer/Filesystem/JsonLinesWriter.php):
+  write items as a json string each on a line of a file.
+- [ChainWriter](../../../../src/batch/src/Job/Item/Writer/ChainWriter.php):
+  write items on multiple item writers.
+- [ConditionalWriter](../../../../src/batch/src/Job/Item/Writer/ConditionalWriter.php):
+  will only write items that are matching your conditions.
+- [DispatchEventsWriter](../../../../src/batch/src/Job/Item/Writer/DispatchEventsWriter.php):
+  will dispatch events before and after writing.
+- [LaunchJobForEachItemWriter](../../../../src/batch/src/Job/Item/Writer/LaunchJobForEachItemWriter.php):
+  launch another job for each items.
+- [LaunchJobForItemsBatchWriter](../../../../src/batch/src/Job/Item/Writer/LaunchJobForItemsBatchWriter.php):
+  launch another job for each item batches.
+- [NullWriter](../../../../src/batch/src/Job/Item/Writer/NullWriter.php):
+  do not write items.
+- [RoutingWriter](../../../../src/batch/src/Job/Item/Writer/RoutingWriter.php):
+  route writing to different writer based on your logic.
+- [SummaryWriter](../../../../src/batch/src/Job/Item/Writer/SummaryWriter.php):
+  write items to a job summary value.
+- [TransformingWriter](../../../../src/batch/src/Job/Item/Writer/TransformingWriter.php):
+  perform items transformation before delegating to another writer.
+- [CallbackWriter](../../../../src/batch/src/Job/Item/Writer/CallbackWriter.php):
+  delegate items write operations to a closure passed at construction.
+
+**Item writers from bridges:**
+- [DispatchEachItemAsMessageWriter (`symfony/messenger`)](../../../../src/batch-symfony-messenger/src/Writer/DispatchEachItemAsMessageWriter.php):
+  dispatch each item as a message in a bus.
+- [DoctrineDBALInsertWriter (`doctrine/dbal`)](../../../../src/batch-doctrine-dbal/src/DoctrineDBALInsertWriter.php):
+  write items by inserting in a table via a Doctrine `Connection`.
+- [DoctrineDBALUpsertWriter (`doctrine/dbal`)](../../../../src/batch-doctrine-dbal/src/DoctrineDBALUpsertWriter.php):
+  write items by inserting/updating in a table via a Doctrine `Connection`.
+- [ObjectWriter (`doctrine/persistence`)](../../../../src/batch-doctrine-persistence/src/ObjectWriter.php):
+  write items to any Doctrine `ObjectManager`.
+- [FlatFileWriter (`openspout/openspout`)](../../../../src/batch-openspout/src/Writer/FlatFileWriter.php):
+  write items to any CSV/ODS/XLSX file.
+
+**Item writers for testing purpose:**
+- [InMemoryWriter](../../../../src/batch/src/Test/Job/Item/Writer/InMemoryWriter.php):
+  write in a private var which can be accessed afterward in your tests.
+- [TestDebugWriter](../../../../src/batch/src/Test/Job/Item/Writer/TestDebugWriter.php):
+  dummy item writer that you can use in your unit tests.
+
+## On the same subject
+
+- [What is an item job ?](../item-job.md)

src/batch/docs/domain/job-execution-storage.md → docs/batch/domain/job-execution-storage.md

@@ -18,33 +18,33 @@ This is [JobLauncher](job-launcher.md)'s job to store it whenever it is required
 
 ## How can I retrieve a Job Execution afterwards ?
 
-Every storage implements [JobExecutionStorageInterface](../../src/Storage/JobExecutionStorageInterface.php) 
+Every storage implements [JobExecutionStorageInterface](../../../src/batch/src/Storage/JobExecutionStorageInterface.php) 
 that has a method called `retrieve`.
 Use this method to retrieve one execution using job name and execution id.
-
+../../../src/batch/src/
 Depending on which storage you decided to use, you may also be able to:
 - list of all executions for particular job, if your storage implements
-  [ListableJobExecutionStorageInterface](../../src/Storage/ListableJobExecutionStorageInterface.php):
+  [ListableJobExecutionStorageInterface](../../../src/batch/src/Storage/ListableJobExecutionStorageInterface.php):
 - filter list of executions matching criteria you provided, if your storage implements
-  [QueryableJobExecutionStorageInterface](../../src/Storage/QueryableJobExecutionStorageInterface.php):
+  [QueryableJobExecutionStorageInterface](../../../src/batch/src/Storage/QueryableJobExecutionStorageInterface.php):
 
 > **Note:** Sometimes the storage may implement these interfaces, but
 > due to the way executions are stored, it might not be recommended heavily rely on these extra methods.
 
 ## What types of storages exists ?
 
 **Built-in storages:**
-- [NullJobExecutionStorage](../../src/Storage/NullJobExecutionStorage.php):
+- [NullJobExecutionStorage](../../../src/batch/src/Storage/NullJobExecutionStorage.php):
   do not persist any job execution.
-- [FilesystemJobExecutionStorage](../../src/Storage/FilesystemJobExecutionStorage.php):
+- [FilesystemJobExecutionStorage](../../../src/batch/src/Storage/FilesystemJobExecutionStorage.php):
   store job executions to a file on local filesystem.
 
 **Storages from bridges:**
-- [DoctrineDBALJobExecutionStorage (`doctrine/dbal`)](https://github.com/yokai-php/batch-doctrine-dbal/blob/0.x/src/DoctrineDBALJobExecutionStorage.php):
+- [DoctrineDBALJobExecutionStorage (`doctrine/dbal`)](../../../src/batch-doctrine-dbal/src/DoctrineDBALJobExecutionStorage.php):
   store job executions to a relational database.
 
 **Storages for testing purpose:**
-- [InMemoryJobExecutionStorage](../../src/Test/Storage/InMemoryJobExecutionStorage.php):
+- [InMemoryJobExecutionStorage](../../../src/batch/src/Test/Storage/InMemoryJobExecutionStorage.php):
   store executions in a private var that can be accessed afterwards in your tests.
 
 ## On the same subject

src/batch/docs/domain/job-execution.md → docs/batch/domain/job-execution.md

@@ -2,7 +2,7 @@
 
 ## What is a Job execution ?
 
-A [JobExecution](../../src/JobExecution.php) is the class that holds information about one execution of a [job](job.md).
+A [JobExecution](../../../src/batch/src/JobExecution.php) is the class that holds information about one execution of a [job](job.md).
 
 ## What kind of information does it hold ?
 

src/batch/docs/domain/job-launcher.md → docs/batch/domain/job-launcher.md

@@ -49,17 +49,17 @@ $execution = $launcher->launch('your.job.name', ['job' => ['configuration']]);
 ## What types of launcher exists ?
 
 **Built-in launchers:**
-- [SimpleJobLauncher](../../src/Launcher/SimpleJobLauncher.php):
+- [SimpleJobLauncher](../../../src/batch/src/Launcher/SimpleJobLauncher.php):
   execute the job directly in the same PHP process.
 
 **Launchers from bridges:**
-- [RunCommandJobLauncher (`symfony/console`)](https://github.com/yokai-php/batch-symfony-console/blob/0.x/src/RunCommandJobLauncher.php):
+- [RunCommandJobLauncher (`symfony/console`)](../../../src/batch-symfony-console/src/RunCommandJobLauncher.php):
   execute the job via an asynchronous symfony command.
-- [DispatchMessageJobLauncher (`symfony/messenger`)](https://github.com/yokai-php/batch-symfony-messenger/blob/0.x/src/DispatchMessageJobLauncher.php):
+- [DispatchMessageJobLauncher (`symfony/messenger`)](../../../src/batch-symfony-messenger/src/DispatchMessageJobLauncher.php):
   execute the job via a symfony message dispatch.
 
 **Launchers for testing purpose:**
-- [BufferingJobLauncher](../../src/Test/Launcher/BufferingJobLauncher.php):
+- [BufferingJobLauncher](../../../src/batch/src/Test/Launcher/BufferingJobLauncher.php):
   do not execute job, but store execution in a private var that can be accessed afterwards in your tests.
 
 ## On the same subject