From eabfedd04ab0cd34a3c771aeffb439f560833956 Mon Sep 17 00:00:00 2001
From: Dantali0n <info@dantalion.nl>
Date: Thu, 28 Sep 2023 16:12:43 +0200
Subject: [PATCH] Backport sphinx documentation to binary wheel package
---
{{cookiecutter.project_slug}}/docs/.gitkeep | 0
{{cookiecutter.project_slug}}/docs/cleanup.sh | 14 +++
.../docs/requirements.txt | 5 +
.../docs/source/conf.py | 93 +++++++++++++++++++
.../docs/source/index.rst | 16 ++++
.../docs/source/readme.rst | 2 +
.../source/source_documentation/index.rst | 7 ++
.../docs/source/static/css/custom.css | 14 +++
{{cookiecutter.project_slug}}/tox.ini | 13 +++
9 files changed, 164 insertions(+)
delete mode 100644 {{cookiecutter.project_slug}}/docs/.gitkeep
create mode 100644 {{cookiecutter.project_slug}}/docs/cleanup.sh
create mode 100644 {{cookiecutter.project_slug}}/docs/requirements.txt
create mode 100644 {{cookiecutter.project_slug}}/docs/source/conf.py
create mode 100644 {{cookiecutter.project_slug}}/docs/source/index.rst
create mode 100644 {{cookiecutter.project_slug}}/docs/source/readme.rst
create mode 100644 {{cookiecutter.project_slug}}/docs/source/source_documentation/index.rst
create mode 100644 {{cookiecutter.project_slug}}/docs/source/static/css/custom.css
diff --git a/{{cookiecutter.project_slug}}/docs/.gitkeep b/{{cookiecutter.project_slug}}/docs/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/{{cookiecutter.project_slug}}/docs/cleanup.sh b/{{cookiecutter.project_slug}}/docs/cleanup.sh
new file mode 100644
index 0000000..aac4cef
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/cleanup.sh
@@ -0,0 +1,14 @@
+#!/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
diff --git a/{{cookiecutter.project_slug}}/docs/requirements.txt b/{{cookiecutter.project_slug}}/docs/requirements.txt
new file mode 100644
index 0000000..3c6e46c
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/requirements.txt
@@ -0,0 +1,5 @@
+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
diff --git a/{{cookiecutter.project_slug}}/docs/source/conf.py b/{{cookiecutter.project_slug}}/docs/source/conf.py
new file mode 100644
index 0000000..c144327
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/conf.py
@@ -0,0 +1,93 @@
+# 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
diff --git a/{{cookiecutter.project_slug}}/docs/source/index.rst b/{{cookiecutter.project_slug}}/docs/source/index.rst
new file mode 100644
index 0000000..65932d2
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/index.rst
@@ -0,0 +1,16 @@
+====================================================
+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
diff --git a/{{cookiecutter.project_slug}}/docs/source/readme.rst b/{{cookiecutter.project_slug}}/docs/source/readme.rst
new file mode 100644
index 0000000..87c96de
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/readme.rst
@@ -0,0 +1,2 @@
+.. include:: ../../README.md
+ :parser: myst_parser.sphinx_
diff --git a/{{cookiecutter.project_slug}}/docs/source/source_documentation/index.rst b/{{cookiecutter.project_slug}}/docs/source/source_documentation/index.rst
new file mode 100644
index 0000000..df6590f
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/source_documentation/index.rst
@@ -0,0 +1,7 @@
+Source code documentation
+=========================
+
+.. toctree::
+ :maxdepth: 3
+
+ {{cookiecutter.project_slug}}
diff --git a/{{cookiecutter.project_slug}}/docs/source/static/css/custom.css b/{{cookiecutter.project_slug}}/docs/source/static/css/custom.css
new file mode 100644
index 0000000..3ea8a2f
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/static/css/custom.css
@@ -0,0 +1,14 @@
+.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;
+}
diff --git a/{{cookiecutter.project_slug}}/tox.ini b/{{cookiecutter.project_slug}}/tox.ini
index 4351731..7fd330f 100644
--- a/{{cookiecutter.project_slug}}/tox.ini
+++ b/{{cookiecutter.project_slug}}/tox.ini
@@ -40,6 +40,19 @@ commands =
format: {envpython} -m autopep8 -v -aa --in-place --recursive tests
format: {envpython} -m black -v src 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-local,build-ci-linux}]
deps =
-r{toxinidir}/tests/requirements.txt
--
GitLab