diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index e012f653816cb1d41beee937735d01d1716bf3af..daa55380aea9c806dec72080af6459375b6d4ca6 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 09cf04420c184d412a17d25151e8a7964783a9e9..07818114dbd72a77522f995dba8c5fa78491e666 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 0000000000000000000000000000000000000000..526f12ca9f4be60b8a615e54076726aa0abf23b4 --- /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 0000000000000000000000000000000000000000..3ef26323853d283b4658ae7fc4a2bda34509c354 --- /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 0000000000000000000000000000000000000000..3602ff8e240d72fbd8f96ead4a05c493b08853e1 --- /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 0000000000000000000000000000000000000000..cc17c1929f8a12504e170563b3760f233dadc37d --- /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 0000000000000000000000000000000000000000..12e286372f4785e67dfea48de3548ae4b9bad7c8 --- /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'