diff options
author | Tristan Van Berkom <tristan.van.berkom@gmail.com> | 2018-08-05 10:57:03 +0000 |
---|---|---|
committer | Tristan Van Berkom <tristan.van.berkom@gmail.com> | 2018-08-05 10:57:03 +0000 |
commit | 63b33d0731dbdf0fdabefad65c7849ba090bdded (patch) | |
tree | d4d682d08f459ee44ddc7ae80003817e118ae146 | |
parent | f918205a2a91beb49ebdcf593b233892c9ebe63c (diff) | |
parent | 9b937a979ec99626711713ca968aee1654c00709 (diff) | |
download | buildstream-63b33d0731dbdf0fdabefad65c7849ba090bdded.tar.gz |
Merge branch 'tristan/build-docs' into 'master'
Build documentation without installing
See merge request BuildStream/buildstream!605
-rw-r--r-- | .gitlab-ci.yml | 1 | ||||
-rw-r--r-- | HACKING.rst | 3 | ||||
-rw-r--r-- | buildstream/__main__.py | 17 | ||||
-rw-r--r-- | doc/Makefile | 8 | ||||
-rwxr-xr-x | doc/bst2html.py | 85 | ||||
-rw-r--r-- | doc/sessions/developing.run | 3 | ||||
-rw-r--r-- | doc/source/advanced-features/junction-elements.rst | 7 |
7 files changed, 62 insertions, 62 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index ff885997d..93fbea779 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -143,7 +143,6 @@ docs: - pip3 install sphinx-click - pip3 install sphinx_rtd_theme - cd dist && ./unpack.sh && cd buildstream - - pip3 install . - make BST_FORCE_SESSION_REBUILD=1 -C doc - cd ../.. - mv dist/buildstream/doc/build/html public diff --git a/HACKING.rst b/HACKING.rst index 78419a69b..7e2914e77 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -261,9 +261,6 @@ using pip or some other mechanism:: # Additional optional dependencies required pip3 install --user arpy -Furthermore, the documentation build requires that BuildStream itself -be installed, as it will be used in the process of generating its docs. - To build the documentation, just run the following:: make -C doc diff --git a/buildstream/__main__.py b/buildstream/__main__.py new file mode 100644 index 000000000..4b0fdabfe --- /dev/null +++ b/buildstream/__main__.py @@ -0,0 +1,17 @@ +################################################################## +# Private Entry Point # +################################################################## +# +# This allows running the cli when BuildStream is uninstalled, +# as long as BuildStream repo is in PYTHONPATH, one can run it +# with: +# +# python3 -m buildstream [program args] +# +# This is used when we need to run BuildStream before installing, +# like when we build documentation. +# +if __name__ == '__main__': + # pylint: disable=no-value-for-parameter + from ._frontend.cli import cli + cli() diff --git a/doc/Makefile b/doc/Makefile index 9a5e98754..51d4513ce 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -31,6 +31,9 @@ ifneq ($(strip $(BST_FORCE_SESSION_REBUILD)),) BST2HTMLOPTS = --force endif +# Help Python find buildstream and its plugins +PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins + .PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean html devhelp @@ -65,7 +68,6 @@ 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 sessions-clean @@ -103,7 +105,7 @@ sessions-prep: # sessions: sessions-prep for file in $(wildcard sessions/*.run); do \ - $(BST2HTML) $(BST2HTMLOPTS) --description $$file; \ + PYTHONPATH=$(PYTHONPATH) $(BST2HTML) $(BST2HTMLOPTS) $$file; \ done sessions-clean: @@ -114,7 +116,7 @@ sessions-clean: # html devhelp: templates sessions @echo "Building $@..." - PYTHONPATH=$(CURDIR)/../buildstream/plugins \ + PYTHONPATH=$(PYTHONPATH) \ $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \ $(wildcard source/*.rst) \ $(wildcard source/tutorial/*.rst) \ diff --git a/doc/bst2html.py b/doc/bst2html.py index c9e98bb36..7bbcf6c9a 100755 --- a/doc/bst2html.py +++ b/doc/bst2html.py @@ -204,7 +204,7 @@ def workdir(source_cache=None): yield (tempdir, bst_config_file, source_cache) -# run_command() +# run_bst_command() # # Runs a command # @@ -216,10 +216,30 @@ def workdir(source_cache=None): # Returns: # (str): The colorized combined stdout/stderr of BuildStream # -def run_command(config_file, directory, command): - click.echo("Running command in directory '{}': bst {}".format(directory, command), err=True) +def run_bst_command(config_file, directory, command): + click.echo("Running bst command in directory '{}': bst {}".format(directory, command), err=True) - argv = ['bst', '--colors', '--config', config_file] + shlex.split(command) + argv = ['python3', '-m', 'buildstream', '--colors', '--config', config_file] + shlex.split(command) + p = subprocess.Popen(argv, cwd=directory, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) + out, _ = p.communicate() + return out.decode('utf-8').strip() + + +# run_shell_command() +# +# Runs a command +# +# Args: +# directory (str): The project directory +# command (str): A shell command +# +# Returns: +# (str): The combined stdout/stderr of the shell command +# +def run_shell_command(directory, command): + click.echo("Running shell command in directory '{}': {}".format(directory, command), err=True) + + argv = shlex.split(command) p = subprocess.Popen(argv, cwd=directory, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) out, _ = p.communicate() return out.decode('utf-8').strip() @@ -373,12 +393,18 @@ def run_session(description, tempdir, source_cache, palette, config_file, force) # Get the command string command_str = _yaml.node_get(command, str, 'command') + # Check whether this is a shell command and not a bst command + is_shell = _yaml.node_get(command, bool, 'shell', default_value=False) + # Check if there is fake output command_fake_output = _yaml.node_get(command, str, 'fake-output', default_value=None) # Run the command, or just use the fake output if command_fake_output is None: - command_out = run_command(config_file, directory, command_str) + if is_shell: + command_out = run_shell_command(directory, command_str) + else: + command_out = run_bst_command(config_file, directory, command_str) else: command_out = command_fake_output @@ -414,14 +440,8 @@ def run_session(description, tempdir, source_cache, palette, config_file, force) @click.option('--palette', '-p', default='tango', type=click.Choice(['solarized', 'solarized-xterm', 'tango', 'xterm', 'console']), help="Selects a palette for the output style") -@click.option('--output', '-o', - type=click.Path(file_okay=True, dir_okay=False, writable=True), - help="A file to store the output") -@click.option('--description', '-d', - type=click.Path(file_okay=True, dir_okay=False, readable=True), - help="A file describing what to do") -@click.argument('command', type=click.STRING, nargs=-1) -def run_bst(directory, force, source_cache, description, palette, output, command): +@click.argument('description', click.Path(file_okay=True, dir_okay=False, readable=True)) +def run_bst(directory, force, source_cache, description, palette): """Run a bst command and capture stdout/stderr in html This command normally takes a description yaml file, see the HACKING @@ -430,45 +450,8 @@ def run_bst(directory, force, source_cache, description, palette, output, comman if not source_cache and os.environ.get('BST_SOURCE_CACHE'): source_cache = os.environ['BST_SOURCE_CACHE'] - if output is not None and not check_needs_build(None, output, force=force): - click.echo("No need to rebuild {}".format(output)) - return 0 - with workdir(source_cache=source_cache) as (tempdir, config_file, source_cache): - - if description: - run_session(description, tempdir, source_cache, palette, config_file, force) - return 0 - - # Run a command specified on the CLI - # - if not directory: - directory = os.getcwd() - else: - directory = os.path.abspath(directory) - directory = os.path.realpath(directory) - - if not command: - command = [] - command_str = " ".join(command) - - # Run the command - # - command_out = run_command(config_file, directory, command_str) - - # Generate a nice html div for this output - # - converted = generate_html(command_out, directory, config_file, - source_cache, tempdir, palette, - command_str) - - if output is None: - click.echo(converted) - else: - outdir = os.path.dirname(output) - os.makedirs(outdir, exist_ok=True) - with open(output, 'wb') as f: - f.write(converted.encode('utf-8')) + run_session(description, tempdir, source_cache, palette, config_file, force) return 0 diff --git a/doc/sessions/developing.run b/doc/sessions/developing.run index 3adb99165..10beb2ad0 100644 --- a/doc/sessions/developing.run +++ b/doc/sessions/developing.run @@ -16,7 +16,8 @@ commands: # Apply a patch in the workspace - directory: ../examples/developing/ - command: show hello.bst; patch workspace_hello/files/src/hello.c update.patch; + shell: True + command: patch workspace_hello/hello.c update.patch # Rebuild - directory: ../examples/developing/ diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst index 81fc01a05..d2d223b88 100644 --- a/doc/source/advanced-features/junction-elements.rst +++ b/doc/source/advanced-features/junction-elements.rst @@ -41,7 +41,7 @@ This element consists of a script which calls hello.bst's hello command. Building callHello.bst, .. raw:: html - :file: ../sessions-stored/junctions-build.html + :file: ../sessions/junctions-build.html You can see that the hello.bst element and it's dependencies from the autotools project have been build as part of the pipeline for callHello.bst. @@ -49,17 +49,18 @@ project have been build as part of the pipeline for callHello.bst. We can now invoke `bst shell` .. raw:: html - :file: ../sessions-stored/junctions-shell.html + :file: ../sessions/junctions-shell.html This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project. + Cross-junction workspaces ------------------------- You can open workspaces for elements in the project refered to by the junction using the syntax `bst open ${junction-name}:{element-name}`. In this example, .. raw:: html - :file: ../sessions-stored/junctions-workspace-open.html + :file: ../sessions/junctions-workspace-open.html This has opened a workspace for the hello.bst element from the autotools project. This workspace can now be used as normal. |