Commit 6da05577 authored by Tristan Van Berkom's avatar Tristan Van Berkom

doc: Improve the new console output html generator

Before we were creating one description file for each output,
making it easier to declare a make rule for it - but the result
was that we would have to build things more and it takes a
long time.

Instead, now we have session files which describe a series of commands
to run in a session, and each command optionally produces an output file.
parent fa73abe4
Pipeline #23825925 passed with stages
in 38 minutes and 41 seconds
......@@ -147,7 +147,7 @@ docs:
- pip3 install sphinx_rtd_theme
- cd dist && ./unpack.sh && cd buildstream
- pip3 install .
- make -C doc clean
- make -C doc sessions
- make -C doc
- cd ../..
- mv dist/buildstream/doc/build/html public
......
......@@ -269,9 +269,9 @@ you can view in your browser locally to test.
Regenerating session html
'''''''''''''''''''''''''
The documentation build will only build the session files if they
are not yet built, and we revision the session files to make it easier
for developers to try documentation changes.
The documentation build will only build the session files if explicitly
asked to. 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
......@@ -279,10 +279,9 @@ will make the docs build reuse already downloaded sources::
export BST_SOURCE_CACHE=~/.cache/buildstream/sources
To force rebuild, simply run the following::
To force build the session html, simply run the following::
make -C doc clean
make -C doc
make -C doc sessions
Man pages
......@@ -375,17 +374,36 @@ included in the reStructuredText documentation at any time with::
.. raw:: html
:file: sessions/${example}.html
The ``.run`` file format is just another YAML dictionary with a few options:
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)
* ``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) at the same time, this ensures that
other developers do not need to regenerate them locally in order to build
the docs.
**Example**:
* ``directory``: The project directory to run commands on, relative to the ``.run`` file.
.. code:: yaml
* ``prepare-commands``: A list of command strings which should be run first
commands:
* ``command``: The command to capture the output of
# Make it fetch first
- directory: ../examples/foo
command: fetch hello.bst
When adding a new ``.run`` file, one should normally also commit a new
generated ``.html`` file at the same time, this ensures that other developers
do not need to regenerate them locally in order to build the docs.
# Capture a build output
- directory: ../examples/foo
output: ../source/sessions/foo-build.html
command: build hello.bst
Testing BuildStream
......
......@@ -26,7 +26,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
BST2HTML = $(CURDIR)/bst2html.py
.PHONY: all clean templates templates-clean html devhelp
.PHONY: all clean templates templates-clean sessions sessions-clean html devhelp
# Canned recipe for generating plugin api skeletons
# $1 = the plugin directory
......@@ -59,11 +59,10 @@ define plugin-doc-skeleton
endef
# We set PYTHONPATH here because source/conf.py sys.modules hacks dont seem to help sphinx-build import the plugins
all: html devhelp
clean: templates-clean
clean: templates-clean sessions-clean
rm -rf build
# Generate rst templates for the docs using a mix of sphinx-apidoc and
......@@ -75,23 +74,26 @@ templates:
$(call plugin-doc-skeleton,$(CURDIR)/../buildstream/plugins/elements,elements)
$(call plugin-doc-skeleton,$(CURDIR)/../buildstream/plugins/sources,sources)
templates-clean:
rm -rf source/elements
rm -rf source/sources
# Generate the html fragments of colorized BuildStream terminal output only
# if they don't yet exist. This is expensive so you need to run `make clean` first
# if you want to regenerate them.
#
SESSION_HTML = $(patsubst sessions/%.run,source/sessions/%.html,$(wildcard sessions/*.run))
source/sessions/%.html:
$(BST2HTML) -o $@ --description $(patsubst source/sessions/%.html,sessions/%.run,$@)
sessions:
for file in "$(wildcard sessions/*.run)"; do \
$(BST2HTML) --description $$file; \
done
templates-clean:
rm -rf source/elements
rm -rf source/sources
sessions-clean:
rm -rf source/sessions
# Targets which generate docs with sphinx build
#
#
html devhelp: templates $(SESSION_HTML)
html devhelp: templates
@echo "Building $@..."
PYTHONPATH=$(CURDIR)/../buildstream/plugins \
$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
......@@ -101,7 +103,3 @@ html devhelp: templates $(SESSION_HTML)
$(wildcard source/sources/*.rst)
@echo
@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"
testy:
@echo "Using $(SPHINXBUILD)"
@echo "Py is $(PYV)"
This diff is collapsed.
# Project directory
directory: ../examples/flatpak-autotools
# Make sure it's fetched in the source cache
prepare-commands:
- fetch hello.bst
# Build it with everything already fetched
command: build hello.bst
# Project directory
directory: ../examples/flatpak-autotools
# Make sure it's fetched and built in the caches
prepare-commands:
- build hello.bst
# Run it now that we know everything is built
command: shell hello.bst -- hello
# Workaround setuptools bug for our symlinks here
#
workaround-symlinks:
../examples/flatpak-autotools/files/links/bin: usr/bin
../examples/flatpak-autotools/files/links/etc: usr/etc
../examples/flatpak-autotools/files/links/lib: usr/lib
commands:
# Make it fetch first
- directory: ../examples/flatpak-autotools
command: fetch hello.bst
# Capture a build output
- directory: ../examples/flatpak-autotools
output: ../source/sessions/flatpak-autotools-build.html
command: build hello.bst
# Capture a shell output
- directory: ../examples/flatpak-autotools
output: ../source/sessions/flatpak-autotools-shell.html
command: shell hello.bst -- hello
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment