From 75c2458c32f502c8278b37a5b14688dda0e21112 Mon Sep 17 00:00:00 2001
From: Davide Gamba <davide.gamba@cern.ch>
Date: Mon, 24 May 2021 18:13:46 +0200
Subject: [PATCH] Trying to build some documentation
---
.gitlab-ci.yml | 11 +++++++-
README.md | 5 ++++
docs/source/api.rst | 13 ++++++++++
docs/source/conf.py | 54 ++++++++++++++++++++++++++++++++++++++++
docs/source/genindex.rst | 6 +++++
docs/source/index.rst | 41 ++++++++++++++++++++++++++++++
docs/source/usage.rst | 26 +++++++++++++++++++
7 files changed, 155 insertions(+), 1 deletion(-)
create mode 100644 docs/source/api.rst
create mode 100644 docs/source/conf.py
create mode 100644 docs/source/genindex.rst
create mode 100644 docs/source/index.rst
create mode 100644 docs/source/usage.rst
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e012f65..daa5538 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,5 +1,4 @@
-
# 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
diff --git a/README.md b/README.md
index 09cf044..0781811 100644
--- a/README.md
+++ b/README.md
@@ -63,3 +63,8 @@ source ./venv/bin/activate
```
python -m pip install -e .
```
+
+6. Created documentation:
+```
+acc-py init-docs
+```
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 0000000..526f12c
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,13 @@
+.. _API_docs:
+
+datascout API documentation
+============================
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree: api
+
+ .. Add the sub-packages that you wish to document below
+
+ datascout
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..3ef2632
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,54 @@
+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
diff --git a/docs/source/genindex.rst b/docs/source/genindex.rst
new file mode 100644
index 0000000..3602ff8
--- /dev/null
+++ b/docs/source/genindex.rst
@@ -0,0 +1,6 @@
+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.
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..cc17c19
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,41 @@
+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
+
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
new file mode 100644
index 0000000..12e2863
--- /dev/null
+++ b/docs/source/usage.rst
@@ -0,0 +1,26 @@
+.. _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'
--
GitLab