[Notes] [Git][BuildStream/buildstream][bochecha/fedora-packages] 8 commits: doc: Build the docs without Buildstream installed



Title: GitLab

Mathieu Bridon pushed to branch bochecha/fedora-packages at BuildStream / buildstream

Commits:

8 changed files:

Changes:

  • .gitlab-ci.yml
    ... ... @@ -143,7 +143,6 @@ docs:
    143 143
       - pip3 install sphinx-click
    
    144 144
       - pip3 install sphinx_rtd_theme
    
    145 145
       - cd dist && ./unpack.sh && cd buildstream
    
    146
    -  - pip3 install .
    
    147 146
       - make BST_FORCE_SESSION_REBUILD=1 -C doc
    
    148 147
       - cd ../..
    
    149 148
       - mv dist/buildstream/doc/build/html public
    

  • HACKING.rst
    ... ... @@ -261,9 +261,6 @@ using pip or some other mechanism::
    261 261
       # Additional optional dependencies required
    
    262 262
       pip3 install --user arpy
    
    263 263
     
    
    264
    -Furthermore, the documentation build requires that BuildStream itself
    
    265
    -be installed, as it will be used in the process of generating its docs.
    
    266
    -
    
    267 264
     To build the documentation, just run the following::
    
    268 265
     
    
    269 266
       make -C doc
    

  • buildstream/__main__.py
    1
    +##################################################################
    
    2
    +#                      Private Entry Point                       #
    
    3
    +##################################################################
    
    4
    +#
    
    5
    +# This allows running the cli when BuildStream is uninstalled,
    
    6
    +# as long as BuildStream repo is in PYTHONPATH, one can run it
    
    7
    +# with:
    
    8
    +#
    
    9
    +#    python3 -m buildstream [program args]
    
    10
    +#
    
    11
    +# This is used when we need to run BuildStream before installing,
    
    12
    +# like when we build documentation.
    
    13
    +#
    
    14
    +if __name__ == '__main__':
    
    15
    +    # pylint: disable=no-value-for-parameter
    
    16
    +    from ._frontend.cli import cli
    
    17
    +    cli()

  • doc/Makefile
    ... ... @@ -31,6 +31,9 @@ ifneq ($(strip $(BST_FORCE_SESSION_REBUILD)),)
    31 31
     BST2HTMLOPTS = --force
    
    32 32
     endif
    
    33 33
     
    
    34
    +# Help Python find buildstream and its plugins
    
    35
    +PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins
    
    36
    +
    
    34 37
     
    
    35 38
     .PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean html devhelp
    
    36 39
     
    
    ... ... @@ -65,7 +68,6 @@ define plugin-doc-skeleton
    65 68
     endef
    
    66 69
     
    
    67 70
     
    
    68
    -# We set PYTHONPATH here because source/conf.py sys.modules hacks dont seem to help sphinx-build import the plugins
    
    69 71
     all: html devhelp
    
    70 72
     
    
    71 73
     clean: templates-clean sessions-clean
    
    ... ... @@ -103,7 +105,7 @@ sessions-prep:
    103 105
     #
    
    104 106
     sessions: sessions-prep
    
    105 107
     	for file in $(wildcard sessions/*.run); do		\
    
    106
    -	    $(BST2HTML) $(BST2HTMLOPTS) --description $$file;	\
    
    108
    +	    PYTHONPATH=$(PYTHONPATH) $(BST2HTML) $(BST2HTMLOPTS) $$file;	\
    
    107 109
     	done
    
    108 110
     
    
    109 111
     sessions-clean:
    
    ... ... @@ -114,7 +116,7 @@ sessions-clean:
    114 116
     #
    
    115 117
     html devhelp: templates sessions
    
    116 118
     	@echo "Building $@..."
    
    117
    -	PYTHONPATH=$(CURDIR)/../buildstream/plugins \
    
    119
    +	PYTHONPATH=$(PYTHONPATH) \
    
    118 120
     	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
    
    119 121
     	    $(wildcard source/*.rst) \
    
    120 122
     	    $(wildcard source/tutorial/*.rst) \
    

  • doc/bst2html.py
    ... ... @@ -204,7 +204,7 @@ def workdir(source_cache=None):
    204 204
             yield (tempdir, bst_config_file, source_cache)
    
    205 205
     
    
    206 206
     
    
    207
    -# run_command()
    
    207
    +# run_bst_command()
    
    208 208
     #
    
    209 209
     # Runs a command
    
    210 210
     #
    
    ... ... @@ -216,10 +216,30 @@ def workdir(source_cache=None):
    216 216
     # Returns:
    
    217 217
     #    (str): The colorized combined stdout/stderr of BuildStream
    
    218 218
     #
    
    219
    -def run_command(config_file, directory, command):
    
    220
    -    click.echo("Running command in directory '{}': bst {}".format(directory, command), err=True)
    
    219
    +def run_bst_command(config_file, directory, command):
    
    220
    +    click.echo("Running bst command in directory '{}': bst {}".format(directory, command), err=True)
    
    221 221
     
    
    222
    -    argv = ['bst', '--colors', '--config', config_file] + shlex.split(command)
    
    222
    +    argv = ['python3', '-m', 'buildstream', '--colors', '--config', config_file] + shlex.split(command)
    
    223
    +    p = subprocess.Popen(argv, cwd=directory, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
    
    224
    +    out, _ = p.communicate()
    
    225
    +    return out.decode('utf-8').strip()
    
    226
    +
    
    227
    +
    
    228
    +# run_shell_command()
    
    229
    +#
    
    230
    +# Runs a command
    
    231
    +#
    
    232
    +# Args:
    
    233
    +#    directory (str): The project directory
    
    234
    +#    command (str): A shell command
    
    235
    +#
    
    236
    +# Returns:
    
    237
    +#    (str): The combined stdout/stderr of the shell command
    
    238
    +#
    
    239
    +def run_shell_command(directory, command):
    
    240
    +    click.echo("Running shell command in directory '{}': {}".format(directory, command), err=True)
    
    241
    +
    
    242
    +    argv = shlex.split(command)
    
    223 243
         p = subprocess.Popen(argv, cwd=directory, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
    
    224 244
         out, _ = p.communicate()
    
    225 245
         return out.decode('utf-8').strip()
    
    ... ... @@ -373,12 +393,18 @@ def run_session(description, tempdir, source_cache, palette, config_file, force)
    373 393
             # Get the command string
    
    374 394
             command_str = _yaml.node_get(command, str, 'command')
    
    375 395
     
    
    396
    +        # Check whether this is a shell command and not a bst command
    
    397
    +        is_shell = _yaml.node_get(command, bool, 'shell', default_value=False)
    
    398
    +
    
    376 399
             # Check if there is fake output
    
    377 400
             command_fake_output = _yaml.node_get(command, str, 'fake-output', default_value=None)
    
    378 401
     
    
    379 402
             # Run the command, or just use the fake output
    
    380 403
             if command_fake_output is None:
    
    381
    -            command_out = run_command(config_file, directory, command_str)
    
    404
    +            if is_shell:
    
    405
    +                command_out = run_shell_command(directory, command_str)
    
    406
    +            else:
    
    407
    +                command_out = run_bst_command(config_file, directory, command_str)
    
    382 408
             else:
    
    383 409
                 command_out = command_fake_output
    
    384 410
     
    
    ... ... @@ -414,14 +440,8 @@ def run_session(description, tempdir, source_cache, palette, config_file, force)
    414 440
     @click.option('--palette', '-p', default='tango',
    
    415 441
                   type=click.Choice(['solarized', 'solarized-xterm', 'tango', 'xterm', 'console']),
    
    416 442
                   help="Selects a palette for the output style")
    
    417
    -@click.option('--output', '-o',
    
    418
    -              type=click.Path(file_okay=True, dir_okay=False, writable=True),
    
    419
    -              help="A file to store the output")
    
    420
    -@click.option('--description', '-d',
    
    421
    -              type=click.Path(file_okay=True, dir_okay=False, readable=True),
    
    422
    -              help="A file describing what to do")
    
    423
    -@click.argument('command', type=click.STRING, nargs=-1)
    
    424
    -def run_bst(directory, force, source_cache, description, palette, output, command):
    
    443
    +@click.argument('description', click.Path(file_okay=True, dir_okay=False, readable=True))
    
    444
    +def run_bst(directory, force, source_cache, description, palette):
    
    425 445
         """Run a bst command and capture stdout/stderr in html
    
    426 446
     
    
    427 447
         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
    430 450
         if not source_cache and os.environ.get('BST_SOURCE_CACHE'):
    
    431 451
             source_cache = os.environ['BST_SOURCE_CACHE']
    
    432 452
     
    
    433
    -    if output is not None and not check_needs_build(None, output, force=force):
    
    434
    -        click.echo("No need to rebuild {}".format(output))
    
    435
    -        return 0
    
    436
    -
    
    437 453
         with workdir(source_cache=source_cache) as (tempdir, config_file, source_cache):
    
    438
    -
    
    439
    -        if description:
    
    440
    -            run_session(description, tempdir, source_cache, palette, config_file, force)
    
    441
    -            return 0
    
    442
    -
    
    443
    -        # Run a command specified on the CLI
    
    444
    -        #
    
    445
    -        if not directory:
    
    446
    -            directory = os.getcwd()
    
    447
    -        else:
    
    448
    -            directory = os.path.abspath(directory)
    
    449
    -            directory = os.path.realpath(directory)
    
    450
    -
    
    451
    -        if not command:
    
    452
    -            command = []
    
    453
    -        command_str = " ".join(command)
    
    454
    -
    
    455
    -        # Run the command
    
    456
    -        #
    
    457
    -        command_out = run_command(config_file, directory, command_str)
    
    458
    -
    
    459
    -        # Generate a nice html div for this output
    
    460
    -        #
    
    461
    -        converted = generate_html(command_out, directory, config_file,
    
    462
    -                                  source_cache, tempdir, palette,
    
    463
    -                                  command_str)
    
    464
    -
    
    465
    -    if output is None:
    
    466
    -        click.echo(converted)
    
    467
    -    else:
    
    468
    -        outdir = os.path.dirname(output)
    
    469
    -        os.makedirs(outdir, exist_ok=True)
    
    470
    -        with open(output, 'wb') as f:
    
    471
    -            f.write(converted.encode('utf-8'))
    
    454
    +        run_session(description, tempdir, source_cache, palette, config_file, force)
    
    472 455
     
    
    473 456
         return 0
    
    474 457
     
    

  • doc/sessions/developing.run
    ... ... @@ -16,7 +16,8 @@ commands:
    16 16
     
    
    17 17
     # Apply a patch in the workspace
    
    18 18
     - directory: ../examples/developing/
    
    19
    -  command: show hello.bst; patch workspace_hello/files/src/hello.c update.patch;
    
    19
    +  shell: True
    
    20
    +  command: patch workspace_hello/hello.c update.patch
    
    20 21
     
    
    21 22
     # Rebuild
    
    22 23
     - directory: ../examples/developing/
    

  • doc/source/advanced-features/junction-elements.rst
    ... ... @@ -41,7 +41,7 @@ This element consists of a script which calls hello.bst's hello command.
    41 41
     Building callHello.bst,
    
    42 42
     
    
    43 43
     .. raw:: html
    
    44
    -   :file: ../sessions-stored/junctions-build.html
    
    44
    +   :file: ../sessions/junctions-build.html
    
    45 45
     
    
    46 46
     You can see that the hello.bst element and it's dependencies from the autotools
    
    47 47
     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.
    49 49
     We can now invoke `bst shell`
    
    50 50
     
    
    51 51
     .. raw:: html
    
    52
    -   :file: ../sessions-stored/junctions-shell.html
    
    52
    +   :file: ../sessions/junctions-shell.html
    
    53 53
     
    
    54 54
     This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project.
    
    55 55
     
    
    56
    +
    
    56 57
     Cross-junction workspaces
    
    57 58
     -------------------------
    
    58 59
     You can open workspaces for elements in the project refered to by the junction
    
    59 60
     using the syntax `bst open ${junction-name}:{element-name}`. In this example,
    
    60 61
     
    
    61 62
     .. raw:: html
    
    62
    -   :file: ../sessions-stored/junctions-workspace-open.html
    
    63
    +   :file: ../sessions/junctions-workspace-open.html
    
    63 64
     
    
    64 65
     This has opened a workspace for the hello.bst element from the autotools project.
    
    65 66
     This workspace can now be used as normal.
    

  • doc/source/install_linux_distro.rst
    ... ... @@ -221,3 +221,15 @@ from `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_
    221 221
     Alternatively, use
    
    222 222
     `buildstream-git <https://aur.archlinux.org/packages/buildstream-git>`_
    
    223 223
     for the lastest version of the development branch.
    
    224
    +
    
    225
    +Fedora
    
    226
    +~~~~~~
    
    227
    +
    
    228
    +BuildStream is not yet in the official Fedora repositories, but you can
    
    229
    +install it from a Copr:
    
    230
    +
    
    231
    +  sudo dnf copr enable bochecha/buildstream
    
    232
    +  sudo dnf install buildstream
    
    233
    +
    
    234
    +Optionally, install the ``buildstream-docs`` package to have the BuildStream
    
    235
    +documentation in Devhelp or GNOME Builder.



  • [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]