Trying to build some documentation

.gitlab-ci.yml

 
-
 # Use the acc-py-devtools templates found at
 # https://gitlab.cern.ch/-/ide/project/acc-co/devops/python/acc-py-devtools/blob/master/-/acc_py_devtools/templates/gitlab-ci/python.yml.
 include:
@@ -24,3 +23,13 @@ test_dev:
 # A push of the source distribution to the acc-py PyPI, only on git tag.
 release_sdist_on_tag:
   extends: .acc_py_release_sdist
+
+
+# A dev build of the documentation, made available through cern.ch/acc-py.
+build_docs:
+  extends: .acc_py_build_docs
+
+
+# A release build of the documentation, made available through cern.ch/acc-py.
+build_docs_on_tag:
+  extends: .acc_py_build_docs_on_tag

README.md

@@ -63,3 +63,8 @@ source ./venv/bin/activate
 ```
 python -m pip install -e .
 ```
+
+6. Created documentation:
+```
+acc-py init-docs
+```

docs/source/api.rst

+.. _API_docs:
+
+datascout API documentation
+============================
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree: api
+
+   .. Add the sub-packages that you wish to document below
+
+   datascout

docs/source/conf.py

+import datetime
+
+import datascout
+
+
+project = "datascout"
+author = "Davide Gamba"
+version = datascout.__version__
+
+copyright = "{0}, CERN".format(datetime.datetime.now().year)
+
+
+# -- 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 = [
+    'acc_py_sphinx.theme',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.napoleon',
+]
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "acc_py"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+html_show_sphinx = False
+html_show_sourcelink = True
+
+
+# -- Options for sphinx.ext.autosummary
+
+autosummary_generate = True
+autosummary_imported_members = True

docs/source/genindex.rst

+A to Z
+======
+
+.. NOTE: The contents of this page are not used, but the page must exist to
+..       prevent a page-not-found sphinx warning when including an a-z index
+..       in the sidebar.

docs/source/index.rst

+datascout
+=========
+
+Introduction
+------------
+
+SHORT DESCRIPTION OF PROJECT
+
+
+Installation
+------------
+
+Using the `acc-py Python package index
+<https://wikis.cern.ch/display/ACCPY/Getting+started+with+acc-python#Gettingstartedwithacc-python-OurPythonPackageRepositoryrepo>`_
+``datascout`` can be pip installed with::
+
+   pip install datascout
+
+
+Documentation contents
+----------------------
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: datascout
+    :maxdepth: 1
+
+    usage
+
+.. toctree::
+    :caption: Reference docs
+    :maxdepth: 1
+
+    api
+    genindex
+

docs/source/usage.rst

+.. _usage:
+
+Usage
+=====
+
+A high-level overview of how to use datascout.
+
+An example:
+
+.. testcode::
+
+    import datascout
+    print(datascout.__name__)
+
+.. testoutput::
+
+    datascout
+
+
+Another example:
+
+.. doctest::
+
+    >>> import datascout
+    >>> datascout.__name__
+    'datascout'