Skip to content
Snippets Groups Projects
Commit 81437c6a authored by Corné Lukken's avatar Corné Lukken
Browse files

Merge branch 'documentation' into 'main'

Add documentation to template

See merge request !23
parents 8c2db649 b1d210ac
No related branches found
No related tags found
1 merge request!23Add documentation to template
Pipeline #59456 passed with warnings
Pipeline: Python Package

#59457

    Showing
    with 188 additions and 4 deletions
    ...@@ -32,3 +32,11 @@ run_unit_tests_coverage: ...@@ -32,3 +32,11 @@ run_unit_tests_coverage:
    path: my_awesome_app/coverage.xml path: my_awesome_app/coverage.xml
    paths: paths:
    - my_awesome_app/htmlcov/* - my_awesome_app/htmlcov/*
    # Override artifact directories
    package_docs:
    stage: package
    artifacts:
    expire_in: 1w
    paths:
    - my_awesome_app/docs/build/*
    \ No newline at end of file
    ...@@ -9,6 +9,10 @@ htmlcov/* ...@@ -9,6 +9,10 @@ htmlcov/*
    build build
    dist dist
    # Documentation
    docs/source/source_documentation
    docs/build
    # Setuptools SCM # Setuptools SCM
    {{cookiecutter.project_slug}}/_version.py {{cookiecutter.project_slug}}/_version.py
    ......
    ...@@ -95,14 +95,12 @@ package_files: ...@@ -95,14 +95,12 @@ package_files:
    package_docs: package_docs:
    stage: package stage: package
    allow_failure: true
    artifacts: artifacts:
    expire_in: 1w expire_in: 1w
    paths: paths:
    - docs/* # update path to match the dest dir for documentation - docs/build/*
    script: script:
    - echo "build and collect docs" - tox -e docs
    - exit 1
    run_integration_tests: run_integration_tests:
    stage: integration stage: integration
    ......
    #!/bin/sh
    FILE_DIR=$(dirname -- "$(readlink -f -- "${0}")")
    echo "Cleaning.. ${FILE_DIR}/source/source_documentation/*"
    for f in "${FILE_DIR}"/source/source_documentation/*
    do
    case $f in
    */index.rst) true;;
    *) echo "Removing.. ${f}"; rm "${f}";;
    esac
    done
    sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD
    sphinx-rtd-theme>=0.4.3 #MIT
    sphinxcontrib-apidoc>=0.3.0 #BSD
    myst-parser>=2.0 # MIT
    docutils>=0.17 # BSD
    # Copyright (C) 2023 ASTRON (Netherlands Institute for Radio Astronomy)
    # SPDX-License-Identifier: Apache-2.0
    import os
    from {{cookiecutter.project_slug}} import __version__
    # -- General configuration ----------------------------------------------------
    # Add any Sphinx extension module names here, as strings. They can be
    # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
    extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinxcontrib.apidoc",
    "sphinx_rtd_theme",
    "myst_parser"
    ]
    # Assumes tox is used to call sphinx-build
    project_root_directory = os.getcwd()
    apidoc_module_dir = "../../{{cookiecutter.project_slug}}"
    apidoc_output_dir = "source_documentation"
    apidoc_excluded_paths = []
    apidoc_separate_modules = True
    apidoc_toc_file = False
    # This should include private methods but does not work
    # https://github.com/sphinx-contrib/apidoc/issues/14
    apidoc_extra_args = ["--private"]
    # The suffix of source filenames.
    source_suffix = [".rst"]
    # The master toctree document.
    master_doc = "index"
    # General information about the project.
    project = "{{cookiecutter.project_name}}"
    copyright = "2023, ASTRON"
    # openstackdocstheme options
    repository_name = "{{cookiecutter.project_url}}"
    bug_project = "none"
    bug_tag = ""
    html_last_updated_fmt = "%Y-%m-%d %H:%M"
    # If true, '()' will be appended to :func: etc. cross-reference text.
    add_function_parentheses = True
    version = __version__
    modindex_common_prefix = ["{{cookiecutter.project_slug}}."]
    # If true, the current module name will be prepended to all description
    # unit titles (such as .. function::).
    add_module_names = True
    # The name of the Pygments (syntax highlighting) style to use.
    pygments_style = "sphinx"
    # -- Options for HTML output --------------------------------------------------
    # The theme to use for HTML and HTML Help pages. Major themes that come with
    # Sphinx are currently 'default' and 'sphinxdoc'.
    # html_theme_path = ["."]
    html_theme = "sphinx_rtd_theme"
    html_static_path = ["static"]
    html_css_files = [
    "css/custom.css",
    ]
    # Output file base name for HTML help builder.
    htmlhelp_basename = "%sdoc" % project
    # Conf.py variables exported to sphinx rst files access using |NAME|
    variables_to_export = [
    "project",
    "copyright",
    "version",
    ]
    # Write to rst_epilog to export `variables_to_export` extract using `locals()`
    # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog
    frozen_locals = dict(locals())
    rst_epilog = "\n".join(
    map(
    lambda x: f".. |{x}| replace:: {frozen_locals[x]}", # noqa: F821
    variables_to_export,
    )
    )
    # Pep is not able to determine that frozen_locals always exists so noqa
    del frozen_locals
    ====================================================
    Welcome to the documentation of {{cookiecutter.project_name}}
    ====================================================
    ..
    To define more variables see rst_epilog generation in conf.py
    Documentation for version: |version|
    Contents:
    .. toctree::
    :maxdepth: 2
    readme
    source_documentation/index
    .. include:: ../../README.md
    :parser: myst_parser.sphinx_
    Source code documentation
    =========================
    .. toctree::
    :maxdepth: 3
    {{cookiecutter.project_slug}}
    .orange { color: #c65d09; }
    .green { color: #5dc609; }
    .yellow { color: #c6c609; }
    .bolditalic {
    font-weight: bold;
    font-style: italic;
    }
    .rst-content code, .rst-content tt, code {
    white-space: break-spaces;
    }
    ...@@ -34,3 +34,4 @@ install_requires = file: requirements.txt ...@@ -34,3 +34,4 @@ install_requires = file: requirements.txt
    [flake8] [flake8]
    max-line-length = 88 max-line-length = 88
    extend-ignore = E203 extend-ignore = E203
    exclude=.venv,.git,.tox,dist,docs,*lib/python*,*egg,_version.py
    # Copyright (C) 2023 ASTRON (Netherlands Institute for Radio Astronomy)
    # SPDX-License-Identifier: Apache-2.0
    """Testing of the Cool Module""" """Testing of the Cool Module"""
    from unittest import TestCase from unittest import TestCase
    ......
    ...@@ -40,6 +40,19 @@ commands = ...@@ -40,6 +40,19 @@ commands =
    format: {envpython} -m autopep8 -v -aa --in-place --recursive tests format: {envpython} -m autopep8 -v -aa --in-place --recursive tests
    format: {envpython} -m black -v {{cookiecutter.project_slug}} tests format: {envpython} -m black -v {{cookiecutter.project_slug}} tests
    [testenv:docs]
    allowlist_externals =
    sh
    ; unset LC_ALL / LANGUAGE from testenv, would fail sphinx otherwise
    setenv =
    deps =
    -r{toxinidir}/requirements.txt
    -r{toxinidir}/docs/requirements.txt
    changedir = {toxinidir}
    commands =
    sh docs/cleanup.sh
    sphinx-build -b html docs/source docs/build/html
    [testenv:build] [testenv:build]
    usedevelop = False usedevelop = False
    commands = {envpython} -m build commands = {envpython} -m build
    # Copyright (C) 2023 ASTRON (Netherlands Institute for Radio Astronomy)
    # SPDX-License-Identifier: Apache-2.0
    """ {{cookiecutter.project_name}} """ """ {{cookiecutter.project_name}} """
    try: try:
    ......
    # Copyright (C) 2023 ASTRON (Netherlands Institute for Radio Astronomy)
    # SPDX-License-Identifier: Apache-2.0
    """ Cool module containing functions, classes and other useful things """ """ Cool module containing functions, classes and other useful things """
    ......
    0% Loading or .
    You are about to add 0 people to the discussion. Proceed with caution.
    Please register or to comment