docs: Documentation generation¶

@@ -20,12 +20,12 @@ install:  ## Install the project in the current environment, with its dependenci
 .PHONY: dev
 dev:  ## Install the project in the current environment, with its dependencies, including the ones needed in a development environment
     @echo "$(BOLD)Installing $(PROJECT_NAME) $(PROJECT_VERSION) in dev mode$(RESET)"
-    @pip install -e .[dev]
+    @pip install -e .[dev,docs]
     @$(MAKE) full-clean

 .PHONY: dev-upgrade
 dev-upgrade:  ## Upgrade all default+dev dependencies defined in setup.cfg
-    @pip install --upgrade `python -c 'import setuptools; o = setuptools.config.read_configuration("setup.cfg")["options"]; print(" ".join(o["install_requires"] + o["extras_require"]["dev"]))'`
+    @pip install --upgrade `python -c 'import setuptools; o = setuptools.config.read_configuration("setup.cfg")["options"]; print(" ".join(o["install_requires"] + o["extras_require"]["dev"] + o["extras_require"]["docs"]))'`
     @pip install -e .
     @$(MAKE) full-clean

@@ -40,7 +40,21 @@ clean:  ## Clean python build related directories and files
     @rm -rf build dist $(PROJECT_NAME).egg-info

 .PHONY: full-clean
-full-clean:  ## Like "clean" but will clean some other generated directories or files
+full-clean:  ## Like "clean" but with clean-doc and will clean some other generated directories or files
 full-clean: clean
     @echo "$(BOLD)Full cleaning$(RESET)"
     find ./ -type d -name '__pycache__' -print0 | xargs -tr0 rm -r
+    -$(MAKE) clean-doc
+
+.PHONY: doc docs
+docs: doc  # we allow "doc" and "docs"
+doc:  clean-doc ## Build the documentation
+    @echo "$(BOLD)Building documentation$(RESET)"
+    @cd docs && $(MAKE) html
+
+.PHONY: clean-docs
+clean-docs: clean-doc  # we allow "clean-doc" and "clean-docs"
+clean-doc:  ## Clean the documentation directories
+    @echo "$(BOLD)Cleaning documentation directories$(RESET)"
+    @rm -rf docs/source
+    @cd docs && $(MAKE) clean

README.rst ¶

Note

View last source and history

Type: Modified
Stats: +11 -0

@@ -131,6 +131,17 @@ Linting
 Documentation
 =============

+We need to document the install process and how to run the application, how to participate and use all the tools, how things works, from a developer point of view and from a user point of view, etc, etc.
+
+All of this will be done via `sphinx <http://www.sphinx-doc.org>`_ and the documentation will be hosted on `ReadTheDocs <https://readthedocs.org>`_.
+
+To build the documentation locally, simply run::
+
+  make docs
+
+
+The documentation will be available at `<https://isshub.readthedocs.io>`_ and will contain everything, including the current document and the documented source code.
+
 Testing
 =======

docs/Makefile ¶

Note

View last source and history

Type: Added
Stats: +19 -0

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file

docs/README.rst ¶

Note

View last source and history

Type: Added
Stats: +46 -0

@@ -0,0 +1,46 @@
+:orphan:
+
+==================================
+Welcome to IssHub's documentation!
+==================================
+
+--------------------
+Online documentation
+--------------------
+
+Documentation is available at `<https://isshub.readthedocs.io>`_
+
+-------
+Content
+-------
+
+This documentation will includes a lot of things, but not everything will be present from day one:
+
+- install process
+- run process
+- dev process and tools
+- how things works from a dev point of view (including source code documentation)
+- how things works from a user point of view
+- ...
+
+-----------
+Local build
+-----------
+
+To build the documentation:
+
+- install dependencies::
+
+    pip install -e .[docs]
+
+- build the documentations::
+
+    make doc
+
+  or::
+
+    cd docs
+    make html
+
+
+Then point your browser to: file:///path/to/isshub/docs/_build/html/index.html

docs/about.rst ¶

Note

View last source and history

Type: Added
Stats: +1 -0

@@ -0,0 +1 @@
+.. include:: ../README.rst

docs/conf.py ¶

Note

View last source and history

Type: Added
Stats: +123 -0

@@ -0,0 +1,123 @@
+# 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:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- 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 glob
+import importlib
+import os
+import subprocess
+import sys
+
+from sphinx.ext import apidoc
+
+
+# for apidoc
+sys.path.insert(0, os.path.abspath("../isshub"))
+
+# default env var to be used by the doc builder, for example readthedocs
+# os.environ.setdefault("XXX", "yyy")
+
+
+# -- Project information -----------------------------------------------------
+
+project = "IssHub"
+copyright = '2019, Stéphane "Twidi" Angel'
+author = 'Stéphane "Twidi" Angel'
+
+
+# -- 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.doctest",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinxprettysearchresults",
+]
+
+# 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"]
+
+# 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.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+html_theme_options = {
+    "navigation_depth": -1,
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+# 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"]
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "isshubdoc"
+
+# -- Extension configuration -------------------------------------------------
+
+html_use_old_search_snippets = True
+
+# -- Run apidoc when building the documentation-------------------------------
+
+
+def run_apidoc(_):
+    """Run apidoc on the marsha project and store source doc in ``source`` dir."""
+    current_dir = os.path.dirname(__file__)
+    source_path = os.path.join(current_dir, "source")
+    output_path = os.path.normpath(os.path.join(current_dir, "..", "isshub"))
+    exclude_paths = [
+        os.path.join(output_path, exclude_path) for exclude_path in ["*/tests/*"]
+    ]
+    apidoc.main(
+        [
+            "--force",
+            "--module-first",
+            "--separate",
+            "--output-dir",
+            source_path,
+            output_path,
+        ]
+        + exclude_paths
+    )
+    subprocess.run(
+        ["sed", "-i", "-e", r"s/ \(module\|package\)$//"]
+        + glob.glob(os.path.join(source_path, "*.rst"))
+    )
+
+
+def setup(app):
+    # Run apidoc
+    app.connect("builder-inited", run_apidoc)

docs/index.rst ¶

Note

View last source and history

Type: Added
Stats: +9 -0

@@ -0,0 +1,9 @@
+==================================
+Welcome to IssHub's documentation!
+==================================
+
+.. toctree::
+  :maxdepth: 2
+
+   About <about>
+   Internals <internals>

docs/internals.rst ¶

Note

View last source and history

Type: Added
Stats: +8 -0

@@ -0,0 +1,8 @@
+================
+IssHub internals
+================
+
+.. toctree::
+  :maxdepth: 2
+
+   Python modules <source/modules>

setup.cfg ¶

Note

View last source and history

Type: Modified
Stats: +5 -0

@@ -28,3 +28,8 @@ packages = find:
 dev =
     ipython
     wheel
+docs =
+    sphinx
+    sphinx-autodoc-typehints
+    sphinx_rtd_theme
+    sphinxprettysearchresults