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

Add documentation to template

parent 8c2db649
No related branches found
No related tags found
1 merge request!23Add documentation to template
Showing
with 188 additions and 4 deletions
......@@ -32,3 +32,11 @@ run_unit_tests_coverage:
path: my_awesome_app/coverage.xml
paths:
- 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/*
build
dist
# Documentation
docs/source/source_documentation
docs/build
# Setuptools SCM
{{cookiecutter.project_slug}}/_version.py
......
......@@ -95,14 +95,12 @@ package_files:
package_docs:
stage: package
allow_failure: true
artifacts:
expire_in: 1w
paths:
- docs/* # update path to match the dest dir for documentation
- docs/build/*
script:
- echo "build and collect docs"
- exit 1
- tox -e docs
run_integration_tests:
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
[flake8]
max-line-length = 88
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"""
from unittest import TestCase
......
......@@ -40,6 +40,19 @@ commands =
format: {envpython} -m autopep8 -v -aa --in-place --recursive 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]
usedevelop = False
commands = {envpython} -m build
# Copyright (C) 2023 ASTRON (Netherlands Institute for Radio Astronomy)
# SPDX-License-Identifier: Apache-2.0
""" {{cookiecutter.project_name}} """
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 """
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment