GNOME.org
 

[Notes] [Git][BuildGrid/buildgrid][mablanch/51-user-facing-docs] 2 commits: Initial Sphinx support for documentation build

Title: GitLab

Martin Blanchard pushed to branch mablanch/51-user-facing-docs at BuildGrid / buildgrid

Commits:

6 changed files:

Changes:

  • .gitlab-ci.yml
    ... ... @@ -2,23 +2,27 @@
    2 2 
     image: python:3.5-stretch
    3 3
    4 4 
     variables:
    5 
    -  BGD: bgd --verbose
    5 
    +  BGD: env/bin/bgd --verbose
    6 6
    7 7 
     stages:
    8 8 
       - test
    9 9 
       - post
    10 10
    11 11 
     before_script:
    12 
    -  - pip3 install setuptools
    13 
    -  - export PATH=~/.local/bin:${PATH}
    14 
    -  - pip3 install --user -e .
    12 
    +  - python3 -m venv env
    13 
    +  - env/bin/python -m pip install --upgrade setuptools pip
    14 
    +  - env/bin/python -m pip install --editable .
    15 15
    16 
    +
    17 
    +#
    18 
    +# Test stage:
    16 19 
     .tests-template: &linux-tests
    17 20 
       stage: test
    18 21 
       variables:
    19 22 
         PYTEST_ADDOPTS: "--color=yes"
    20 23 
       script:
    21 
    -    - python3 setup.py test
    24 
    +    - env/bin/python -m pip install --editable ".[tests]"
    25 
    +    - env/bin/python setup.py test
    22 26 
         - mkdir -p coverage/
    23 27 
         - cp .coverage.* coverage/coverage."${CI_JOB_NAME}"
    24 28 
       artifacts:
    ... ... @@ -40,29 +44,42 @@ run-dummy-job-debian:
    40 44 
       image: buildstream/buildstream-debian
    41 45 
       <<: *dummy-job
    42 46
    47 
    +build-docs:
    48 
    +  stage: test
    49 
    +  script:
    50 
    +    - env/bin/python -m pip install --editable ".[docs]"
    51 
    +    - env/bin/python setup.py build_sphinx
    52 
    +    - cp -rf build/sphinx/html public
    53 
    +  artifacts:
    54 
    +    paths:
    55 
    +    - public/
    56 
    +
    43 57
    58 
    +#
    59 
    +# Post stage:
    44 60 
     coverage:
    45 61 
       stage: post
    46 62 
       coverage: '/TOTAL +\d+ +\d+ +(\d+\.\d+)%/'
    47 63 
       script:
    48 
    -    - pip3 install coverage==4.4.0
    64 
    +    - env/bin/python -m pip install coverage==4.4.0
    49 65 
         - mkdir report
    50 66 
         - cd report
    51 67 
         - cp ../coverage/coverage.* .
    52 68 
         - ls coverage.*
    53 
    -    - coverage combine --rcfile=../.coveragerc -a coverage.*
    54 
    -    - coverage report --rcfile=../.coveragerc -m
    69 
    +    - env/bin/coverage combine --rcfile=../.coveragerc -a coverage.*
    70 
    +    - env/bin/coverage report --rcfile=../.coveragerc -m
    55 71 
       dependencies:
    56 72 
       - tests-debian-stretch
    57 73
    58 
    -# Deploy, only for merges which land on master branch.
    74 
    +
    59 75 
     #
    76 
    +# Deploy stage (master only):
    60 77 
     pages:
    61 78 
       stage: post
    62 79 
       dependencies:
    63 
    -  - tests-debian-stretch
    80 
    +  - build-docs
    64 81 
       script:
    65 
    -  - mv coverage/ public/
    82 
    +  - find public/
    66 83 
       artifacts:
    67 84 
         paths:
    68 85 
         - public/

  • docs/Makefile
    1 
    +# Minimal makefile for Sphinx documentation
    2 
    +#
    3 
    +
    4 
    +# You can set these variables from the command line.
    5 
    +SPHINXOPTS    =
    6 
    +SPHINXBUILD   = sphinx-build
    7 
    +SPHINXPROJ    = BuildGrid
    8 
    +SOURCEDIR     = source
    9 
    +BUILDDIR      = build
    10 
    +
    11 
    +# Put it first so that "make" without argument is like "make help".
    12 
    +help:
    13 
    +	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
    14 
    +
    15 
    +.PHONY: help Makefile
    16 
    +
    17 
    +# Catch-all target: route all unknown targets to Sphinx using the new
    18 
    +# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
    19 
    +%: Makefile
    20 
    +	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
    \ No newline at end of file

  • docs/source/conf.py
    1 
    +#!/usr/bin/env python3
    2 
    +# -*- coding: utf-8 -*-
    3 
    +#
    4 
    +# pylint: skip-file
    5 
    +#
    6 
    +# Configuration file for the Sphinx documentation builder.
    7 
    +#
    8 
    +# This file does only contain a selection of the most common options. For a
    9 
    +# full list see the documentation:
    10 
    +# http://www.sphinx-doc.org/en/master/config
    11 
    +
    12 
    +# -- Path setup --------------------------------------------------------------
    13 
    +
    14 
    +# If extensions (or modules to document with autodoc) are in another directory,
    15 
    +# add these directories to sys.path here. If the directory is relative to the
    16 
    +# documentation root, use os.path.abspath to make it absolute, like shown here.
    17 
    +#
    18 
    +import os
    19 
    +import sys
    20 
    +sys.path.insert(0, os.path.abspath('..'))
    21 
    +
    22 
    +from _version import __version__
    23 
    +
    24 
    +# -- Project information -----------------------------------------------------
    25 
    +
    26 
    +project = 'BuildGrid'
    27 
    +copyright = '2018, The BuildGrid Contributors'
    28 
    +author = 'The BuildGrid Contributors'
    29 
    +
    30 
    +# The short X.Y version
    31 
    +version = __version__
    32 
    +# The full version, including alpha/beta/rc tags
    33 
    +release = __version__
    34 
    +
    35 
    +
    36 
    +# -- General configuration ---------------------------------------------------
    37 
    +
    38 
    +# If your documentation needs a minimal Sphinx version, state it here.
    39 
    +#
    40 
    +# needs_sphinx = '1.0'
    41 
    +
    42 
    +# Add any Sphinx extension module names here, as strings. They can be
    43 
    +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
    44 
    +# ones.
    45 
    +extensions = [
    46 
    +    'sphinx.ext.autodoc',
    47 
    +    'sphinx.ext.napoleon',
    48 
    +    'sphinx_click.ext'
    49 
    +]
    50 
    +
    51 
    +# Add any paths that contain templates here, relative to this directory.
    52 
    +templates_path = ['templates']
    53 
    +
    54 
    +# The suffix(es) of source filenames.
    55 
    +# You can specify multiple suffix as a list of string:
    56 
    +#
    57 
    +# source_suffix = ['.rst', '.md']
    58 
    +source_suffix = '.rst'
    59 
    +
    60 
    +# The master toctree document.
    61 
    +master_doc = 'index'
    62 
    +
    63 
    +# The language for content autogenerated by Sphinx. Refer to documentation
    64 
    +# for a list of supported languages.
    65 
    +#
    66 
    +# This is also used if you do content translation via gettext catalogs.
    67 
    +# Usually you set "language" from the command line for these cases.
    68 
    +language = None
    69 
    +
    70 
    +# List of patterns, relative to source directory, that match files and
    71 
    +# directories to ignore when looking for source files.
    72 
    +# This pattern also affects html_static_path and html_extra_path .
    73 
    +exclude_patterns = []
    74 
    +
    75 
    +# The name of the Pygments (syntax highlighting) style to use.
    76 
    +pygments_style = 'sphinx'
    77 
    +
    78 
    +
    79 
    +# -- Options for HTML output -------------------------------------------------
    80 
    +
    81 
    +# The theme to use for HTML and HTML Help pages.  See the documentation for
    82 
    +# a list of builtin themes.
    83 
    +#
    84 
    +html_theme = 'sphinx_rtd_theme'
    85 
    +
    86 
    +# Theme options are theme-specific and customize the look and feel of a theme
    87 
    +# further.  For a list of options available for each theme, see the
    88 
    +# documentation.
    89 
    +#
    90 
    +# html_theme_options = {}
    91 
    +
    92 
    +# Add any paths that contain custom static files (such as style sheets) here,
    93 
    +# relative to this directory. They are copied after the builtin static files,
    94 
    +# so a file named "default.css" will overwrite the builtin "default.css".
    95 
    +# html_static_path = ['static']
    96 
    +
    97 
    +# Custom sidebar templates, must be a dictionary that maps document names
    98 
    +# to template names.
    99 
    +#
    100 
    +# The default sidebars (for documents that don't match any pattern) are
    101 
    +# defined by theme itself.  Builtin themes are using these templates by
    102 
    +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
    103 
    +# 'searchbox.html']``.
    104 
    +#
    105 
    +# html_sidebars = {}
    106 
    +
    107 
    +
    108 
    +# -- Options for HTMLHelp output ---------------------------------------------
    109 
    +
    110 
    +# Output file base name for HTML help builder.
    111 
    +htmlhelp_basename = 'BuildGriddoc'
    112 
    +
    113 
    +
    114 
    +# -- Options for LaTeX output ------------------------------------------------
    115 
    +
    116 
    +latex_elements = {
    117 
    +    # The paper size ('letterpaper' or 'a4paper').
    118 
    +    #
    119 
    +    # 'papersize': 'letterpaper',
    120 
    +
    121 
    +    # The font size ('10pt', '11pt' or '12pt').
    122 
    +    #
    123 
    +    # 'pointsize': '10pt',
    124 
    +
    125 
    +    # Additional stuff for the LaTeX preamble.
    126 
    +    #
    127 
    +    # 'preamble': '',
    128 
    +
    129 
    +    # Latex figure (float) alignment
    130 
    +    #
    131 
    +    # 'figure_align': 'htbp',
    132 
    +}
    133 
    +
    134 
    +# Grouping the document tree into LaTeX files. List of tuples
    135 
    +# (source start file, target name, title,
    136 
    +#  author, documentclass [howto, manual, or own class]).
    137 
    +latex_documents = [
    138 
    +    (master_doc, 'BuildGrid.tex', 'BuildGrid Documentation',
    139 
    +     'The BuildGrid Contributors', 'manual'),
    140 
    +]
    141 
    +
    142 
    +
    143 
    +# -- Options for manual page output ------------------------------------------
    144 
    +
    145 
    +# One entry per manual page. List of tuples
    146 
    +# (source start file, name, description, authors, manual section).
    147 
    +man_pages = [
    148 
    +    (master_doc, 'buildgrid', 'BuildGrid Documentation',
    149 
    +     [author], 1)
    150 
    +]
    151 
    +
    152 
    +
    153 
    +# -- Options for Texinfo output ----------------------------------------------
    154 
    +
    155 
    +# Grouping the document tree into Texinfo files. List of tuples
    156 
    +# (source start file, target name, title, author,
    157 
    +#  dir menu entry, description, category)
    158 
    +texinfo_documents = [
    159 
    +    (master_doc, 'BuildGrid', 'BuildGrid Documentation',
    160 
    +     author, 'BuildGrid', 'One line description of project.',
    161 
    +     'Miscellaneous'),
    162 
    +]

  • docs/source/index.rst
    1 
    +.. BuildGrid documentation master file, created by
    2 
    +   sphinx-quickstart on Tue Aug 14 16:51:30 2018.
    3 
    +   You can adapt this file completely to your liking, but it should at least
    4 
    +   contain the root `toctree` directive.
    5 
    +
    6 
    +BuildGrid's documentation
    7 
    +=========================
    8 
    +
    9 
    +.. toctree::
    10 
    +   :maxdepth: 2
    11 
    +   :caption: Contents:
    12 
    +
    13 
    +
    14 
    +Resources
    15 
    +---------
    16 
    +
    17 
    +* Homepage: https://www.buildgrid.build
    18 
    +* GitLab repository: https://gitlab.com/BuildGrid/buildgrid
    19 
    +* Bug Tracking: https://gitlab.com/BuildGrid/buildgrid/issues
    20 
    +* Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
    21 
    +* IRC Channel: irc://chat.freenode.net/#buildgrid

  • setup.cfg
    ... ... @@ -11,5 +11,6 @@ pep8ignore =
    11 11 
         */lib/python3* ALL
    12 12 
         */bin/* ALL
    13 13 
         .eggs/* ALL
    14 
    +    docs/source/conf.py ALL
    14 15 
         *_pb2.py ALL
    15 16 
         *_pb2_grpc.py ALL

  • setup.py
    ... ... @@ -95,6 +95,14 @@ tests_require = [
    95 95 
         'pytest-pylint',
    96 96 
     ]
    97 97
    98 
    +docs_require = [
    99 
    +    'sphinx',
    100 
    +    'sphinx-click',
    101 
    +    'sphinx-rtd-theme',
    102 
    +    'sphinxcontrib-apidoc',
    103 
    +    'sphinxcontrib-napoleon',
    104 
    +]
    105 
    +
    98 106 
     setup(
    99 107 
         name="BuildGrid",
    100 108 
         version=__version__,
    ... ... @@ -117,6 +125,7 @@ setup(
    117 125 
         setup_requires=['pytest-runner'],
    118 126 
         tests_require=tests_require,
    119 127 
         extras_require={
    120 
    -        'devel': tests_require,
    128 
    +        'docs': docs_require,
    129 
    +        'tests': tests_require,
    121 130 
         },
    122 131 
     )

    • —
    View it on GitLab.
    You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.

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