Update readme.

Author: tobiasraabe

README.rst

@@ -37,8 +37,8 @@ pytask-latex
 pytask-latex allows you to compile LaTeX documents.
 
 It also tries to infer the dependency of the LaTeX document such as included images,
-bibliography files and other .tex files automatically to compile LaTeX documents when it
-is possible.
+bibliography files and other ``.tex`` files automatically to compile LaTeX documents
+when it is possible.
 
 
 Installation
@@ -72,7 +72,7 @@ popular LaTeX distributions, like `MiKTeX <https://miktex.org/>`_, `TeX Live
 Usage
 -----
 
-Here is an example where you want to compile ``document.tex`` to a PDF.
+Compiling your PDF can be as simple as writing the following task.
 
 .. code-block:: python
 
@@ -85,9 +85,9 @@ Here is an example where you want to compile ``document.tex`` to a PDF.
     def task_compile_latex_document():
         pass
 
-When the task is executed, you find a ``document.pdf`` in the same folder as your
-``document.tex``, but you could also compile the report into a another folder by
-changing the path in ``produces``.
+Use ``@pytask.mark.latex`` to indicate that this task compiles a LaTeX document.
+``@pytask.mark.depends_on`` points to the source file which is compiled and
+``@pytask.mark.produces`` is the path of the compiled PDF.
 
 
 Multiple dependencies and products
@@ -139,39 +139,72 @@ The same applies to the compiled document which is either in the first position,
 the key ``"document"`` or ``0``.
 
 
-Command Line Arguments
-~~~~~~~~~~~~~~~~~~~~~~
+Customizing the compilation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To customize the compilation, you can pass some command line arguments to ``latexmk``
-via the ``@pytask.mark.latex`` marker. The default is the following.
+pytask-latex uses latexmk by default to compile the document because it handles most
+use-cases automatically. The following is equivalent to a bare ``@pytask.mark.latex``
+decorator.
 
 .. code-block:: python
 
-    @pytask.mark.latex(["--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd"])
+    @pytask.mark.latex(build_steps="latexmk")
     def task_compile_latex_document():
-        pass
+        ...
+
+The ``@pytask.mark.latex`` decorator has a keyword argument called ``build_steps`` which
+accepts which accepts strings or list of strings pointing to internally implemented
+build steps. Using strings will use the default configuration of this build step. It is
+equivalent to the following.
+
+.. code-block::
+
+    from pytask_latex import build_steps
+
+
+    @pytask.mark.latex(
+        build_steps=build_steps.latexmk(
+            options=("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
+        )
+    )
+    def task_compile_latex_document():
+        ...
+
+In this example, ``build_steps.latexmk`` is a build step constructor which accepts a set
+of options and creates a build step function out of it.
 
-For example, to compile your document with XeLaTeX, use
+You can pass different options to change the compilation process with latexmk. Here is
+an example for generating a ``.dvi``.
 
 .. code-block:: python
 
-    @pytask.mark.latex(["--xelatex", "--interaction=nonstopmode"])
+    @pytask.mark.latex(
+        build_steps=build_steps.latexmk(
+            options=("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
+        )
+    )
     def task_compile_latex_document():
-        pass
+        ...
 
-The options ``--jobname``, ``--output-directory`` and the ``.tex`` file which will be
-compiled are automatically handled and inferred from the ``@pytask.mark.depends_on`` and
-``@pytask.mark.produces`` markers.
+``build_step.latexmk(options)`` generates a build step which is a function with the
+following signature:
 
-The ``@pytask.mark.latex`` accepts both, a string or a list of strings with options.
+.. code-block::
 
-For more options and their explanations, visit the `latexmk manual
-<https://man.cx/latexmk>`_ or type the following commands.
+    from pathlib import Path
+    import subprocess
 
-.. code-block:: console
 
-    $ latexmk -h
-    $ latexmk -showextraoptions
+    def custom_build_step(path_to_tex: Path, path_to_document: Path) -> None:
+        ...
+        subproces.run(..., check=True)
+
+Each build step receives the path to the LaTeX source file and the path to the final
+document which it uses to call some program on the command line to run another step in
+the compilation process.
+
+In the future, pytask-latex will provide more build steps for compiling bibliographies,
+glossaries and the like.
 
 
 Parametrization
@@ -195,7 +228,8 @@ The following task compiles two latex documents.
 
 If you want to compile the same document with different command line options, you have
 to include the latex decorator in the parametrization just like with
-``@pytask.mark.depends_on`` and ``@pytask.mark.produces``.
+``@pytask.mark.depends_on`` and ``@pytask.mark.produces``. Pass a dictionary for
+possible build steps and their options.
 
 .. code-block:: python
 
@@ -205,11 +239,19 @@ to include the latex decorator in the parametrization just like with
         [
             (
                 "document.pdf",
-                ("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd"),
+                {
+                    "build_steps": build_steps.latexmk(
+                        ("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
+                    )
+                },
             ),
             (
                 "document.dvi",
-                ("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd"),
+                {
+                    "build_steps": build_steps.latexmk(
+                        ("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
+                    )
+                },
             ),
         ],
     )