From 9e204cf831e71b71ed80abcd0227203b173cfd38 Mon Sep 17 00:00:00 2001 From: Dilawar Singh Date: Sat, 7 Aug 2021 10:30:43 +0530 Subject: [PATCH 1/3] Squashed commit of the following: commit 7ca2647bc381f6023c605b860c38534da5c780c4 Author: Dilawar Singh Date: Sat Aug 7 10:19:55 2021 +0530 reverted toy_example.py commit e1bba0eab1148014cf61dca7a9b62983fc79f5e4 Author: Dilawar Singh Date: Sat Aug 7 10:19:41 2021 +0530 Added readthedocs files. --- docs/conf.py | 71 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 22 ++++++++++++++ docs/requirements.txt | 5 +++ 3 files changed, 98 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..5c3bae2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,71 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +# -- Project information ----------------------------------------------------- + +project = "epimargin" +copyright = "2021, Satej Soman, Caitlin Loftus, Steven Buschbach, Manasi Phadnis, Luís M. A. Bettencourt" +author = "Satej Soman, Caitlin Loftus, Steven Buschbach, Manasi Phadnis, Luís M. A. Bettencourt" + + +# -- 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.napoleon", + "sphinx_autodoc_typehints", + "sphinx_rtd_theme", +] + +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 2 + +autoclass_content = "both" +autodoc_default_options = { + "member-order": "bysource", + # "special-members": "__init__", + "undoc-members": True, + "show_inheritance": True, + "inherited-members": True, +} + +autosummary_generate = True + +# 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 = ["_build", "Thumbs.db", ".DS_Store"] + + + +# -- 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 = "sphinx_rtd_theme" + +# 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"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..61d9743 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +Welcome to epimargin's documentation! +===================================== + +.. image:: https://github.com/COVID-IWG/epimargin/raw/master/docs/logo.svg + :width: 300 + +API Documentation +================== + +.. automodule:: epimargin + :members: + +.. toctree:: + :maxdepth: 3 + :caption: Table of Contents + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..8ff3e9d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinxcontrib-napoleon +sphinx-autodoc-typehints +sphinx_rtd_theme +commonmark +rst_include From 76caeb8fd94cb1d2232216f95914a3890329f716 Mon Sep 17 00:00:00 2001 From: Dilawar Singh Date: Sat, 7 Aug 2021 11:06:34 +0530 Subject: [PATCH 2/3] doc:rtd: run sphinx-apidoc before running final stage --- docs/conf.py | 12 ++++++++++++ docs/index.rst | 12 ++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5c3bae2..24c74a1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,9 +12,21 @@ # import os import sys +from pathlib import Path sys.path.insert(0, os.path.abspath("..")) +try: + # version > 3.0 + from sphinx.ext.apidoc import main as apidoc_main +except ImportError: + # sphinx version < 3 + from sphinx.apidoc import main as apidoc_main + +cwd = Path(__file__).parent +module = cwd / '..' / 'epimargin' +apidoc_main(['-e', '-o', str(cwd), str(module), '--force']) + # -- Project information ----------------------------------------------------- project = "epimargin" diff --git a/docs/index.rst b/docs/index.rst index 61d9743..5f6be14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,12 +7,16 @@ Welcome to epimargin's documentation! API Documentation ================== -.. automodule:: epimargin - :members: + +.. + comment: module.rst and epimargin.rst are generated by sphinx-build at run time. + See conf.py file. + .. toctree:: - :maxdepth: 3 - :caption: Table of Contents + + modules + Indices and tables ================== From 0261117cb29dd233600d8f0410d79c93ba261fd3 Mon Sep 17 00:00:00 2001 From: Dilawar Singh Date: Sat, 7 Aug 2021 11:14:17 +0530 Subject: [PATCH 3/3] hack: use environment variable to pass autodoc options to generator. --- docs/conf.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 24c74a1..836fdff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,9 +23,6 @@ # sphinx version < 3 from sphinx.apidoc import main as apidoc_main -cwd = Path(__file__).parent -module = cwd / '..' / 'epimargin' -apidoc_main(['-e', '-o', str(cwd), str(module), '--force']) # -- Project information ----------------------------------------------------- @@ -50,14 +47,23 @@ autosectionlabel_maxdepth = 2 autoclass_content = "both" + autodoc_default_options = { "member-order": "bysource", - # "special-members": "__init__", + "special-members": "__init__", "undoc-members": True, "show_inheritance": True, "inherited-members": True, } +# hack to generate apidoc automatically. +cwd = Path(__file__).parent +module = cwd / ".." / "epimargin" +os.environ["SPHINX_APIDOC_OPTIONS"] = ",".join( + [f"{k}={v}" for k, v in autodoc_default_options.items()] +) +apidoc_main(["-e", "-o", str(cwd), str(module), "--force"]) + autosummary_generate = True # Add any paths that contain templates here, relative to this directory. @@ -69,7 +75,6 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for