diff options
Diffstat (limited to 'HACKING.rst')
| -rw-r--r-- | HACKING.rst | 101 |
1 files changed, 98 insertions, 3 deletions
diff --git a/HACKING.rst b/HACKING.rst index 76aab91a7..dd791bd24 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -1,5 +1,5 @@ -Hacking on BuildStream -====================== +Contributing +============ Some tips and guidelines for developers hacking on BuildStream @@ -257,7 +257,7 @@ using pip or some other mechanism:: pip3 install --user arpy Furthermore, the documentation build requires that BuildStream itself -be installed. +be installed, as it will be used in the process of generating its docs. To build the documentation, just run the following:: @@ -267,6 +267,23 @@ This will give you a ``doc/build/html`` directory with the html docs which you can view in your browser locally to test. +Regenerating session html +''''''''''''''''''''''''' +The documentation build will build the session files if they are missing, +or if explicitly asked to rebuild. We revision the generated session html files +in order to reduce the burden on documentation contributors. + +To explicitly rebuild the session snapshot html files, it is recommended that you +first set the ``BST_SOURCE_CACHE`` environment variable to your source cache, this +will make the docs build reuse already downloaded sources:: + + export BST_SOURCE_CACHE=~/.cache/buildstream/sources + +To force rebuild session html while building the doc, simply build the docs like this:: + + make BST_FORCE_SESSION_REBUILD=1 -C doc + + Man pages ~~~~~~~~~ Unfortunately it is quite difficult to integrate the man pages build @@ -314,6 +331,84 @@ format:: """ +Documentation Examples +~~~~~~~~~~~~~~~~~~~~~~ +The examples section of the documentation contains a series of standalone +examples, here are the criteria for an example addition. + +* The example has a ``${name}`` + +* The example has a project users can copy and use + + * This project is added in the directory ``doc/examples/${name}`` + +* The example has a documentation component + + * This is added at ``doc/source/examples/${name}.rst`` + * A reference to ``examples/${name}`` is added to the toctree in ``doc/source/examples.rst`` + * This documentation discusses the project elements declared in the project and may + provide some BuildStream command examples + * This documentation links out to the reference manual at every opportunity + +* The example has a CI test component + + * This is an integration test added at ``tests/examples/${name}`` + * This test runs BuildStream in the ways described in the example + and assert that we get the results which we advertize to users in + the said examples. + + +Adding BuildStream command output +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +As a part of building the docs, BuildStream will run itself and extract +some html for the colorized output which is produced. + +If you want to run BuildStream to produce some nice html for your +documentation, then you can do so by adding new ``.run`` files to the +``doc/sessions/`` directory. + +Any files added as ``doc/sessions/${example}.run`` will result in generated +file at ``doc/source/sessions/${example}.html``, and these files can be +included in the reStructuredText documentation at any time with:: + + .. raw:: html + :file: sessions/${example}.html + +The ``.run`` file format is just another YAML dictionary which consists of a +``commands`` list, instructing the program what to do command by command. + +Each *command* is a dictionary, the members of which are listed here: + +* ``directory``: The input file relative project directory + +* ``output``: The input file relative output html file to generate (optional) + +* ``fake-output``: Don't really run the command, just pretend to and pretend + this was the output, an empty string will enable this too. + +* ``command``: The command to run, without the leading ``bst`` + +When adding a new ``.run`` file, one should normally also commit the new +resulting generated ``.html`` file(s) into the ``doc/source/sessions-stored/`` +directory at the same time, this ensures that other developers do not need to +regenerate them locally in order to build the docs. + +**Example**: + +.. code:: yaml + + commands: + + # Make it fetch first + - directory: ../examples/foo + command: fetch hello.bst + + # Capture a build output + - directory: ../examples/foo + output: ../source/sessions/foo-build.html + command: build hello.bst + + Testing BuildStream ------------------- BuildStream uses pytest for regression tests and testing out |