feat(doc): ajout d'une infra de documentation, servie en ligne via django-docs

.gitignore

@@ -41,3 +41,4 @@ var/
 # builds
 styleguide/index.html
 benevalibre/static/
+docs/build/

Makefile

@@ -60,7 +60,7 @@ endif
 
 # Définition des cibles -------------------------------------------------------
 
-.PHONY: clean-pyc clean-build clear-venv help check check-config
+.PHONY: clean-pyc clean-build clear-venv help check check-config docs clean-docs
 .DEFAULT_GOAL := help
 
 # Commentaire d'une cible : #-> interne ##-> aide production+dev ###-> aide dev
@@ -157,3 +157,9 @@ fix-lint: ### corrige la syntaxe et ordonne les imports python
 ifdef USE_BLACK
 	$(PYTHON) -m black benevalibre
 endif
+
+docs: ## construit la documentation
+	$(MAKE) -C docs/ html SPHINXBUILD=../$(VENV_DIR)/bin/sphinx-build
+
+clean-docs:  ## supprime la documentation (docs/build)
+	$(MAKE) -C docs/ clean SPHINXBUILD=../$(VENV_DIR)/bin/sphinx-build

benevalibre/settings/base.py

@@ -84,6 +84,7 @@ THIRD_PARTY_APPS = [
     'tapeforms',
     'django_tables2',
     'cruditor',
+    'docs',
 ]
 
 # Project applications
@@ -262,6 +263,11 @@ CSRF_COOKIE_PATH = APP_LOCATION
 # https://django-registration-redux.readthedocs.io/en/latest/default-backend.html
 ACCOUNT_ACTIVATION_DAYS = 3
 
+# DOCS
+# ------------------------------------------------------------------------------
+# https://django-docs.readthedocs.io/en/latest/
+DOCS_ROOT = base_dir('docs/build/html')
+
 # ASSOCIATION REGISTRATION
 # ------------------------------------------------------------------------------
 # Any registered guest can register an association

benevalibre/urls.py

@@ -2,6 +2,7 @@ from django.conf import settings
 from django.urls import include, path
 
 urlpatterns = [
+    path('docs/', include('docs.urls')),
     path('account/', include('benevalibre.accounts.urls')),
     path('association/', include('benevalibre.association.urls')),
     path('benevalo/', include('benevalibre.benevalo.urls')),

docs/Makefile

@@ -0,0 +1,22 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees
+
+.PHONY: help clean html linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(ALLSPHINXOPTS)
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(ALLSPHINXOPTS)

docs/source/conf.py

@@ -0,0 +1,116 @@
+"""
+Documentation build's configuration for Benevalibre.
+
+This file does only contain a selection of the most common options. For a
+full list see the documentation:
+http://www.sphinx-doc.org/en/master/config
+"""
+import os
+import sys
+import django
+sys.path.insert(0, os.path.abspath('../..'))
+from benevalibre.settings import DJANGO_SETTINGS_MODULE                         
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', DJANGO_SETTINGS_MODULE)     
+django.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.
+sys.path.insert(0, os.path.abspath('../../'))
+
+# sys.setrecursionlimit(1500)  # default is usually about 1000
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'benevalibre.settings.test')
+
+
+# -- Project information -----------------------------------------------------
+
+from benevalibre import __version__  # noqa: E402
+
+project = "Bénévalibre"
+author = "Cliss XXI"
+copyright = "2019, Cliss XXI, released under the GNU AGPLv3+ License"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = __version__
+# The full version, including alpha/beta/rc tags.
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = ['.rst']
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'fr'
+
+# 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 = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- 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'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {'logo_only': True}
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "Documentation de Bénévalibre"
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+html_short_title = "Documentation"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = '../../artwork/benevalibre-white.svg'
+
+# 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']
+
+# If true, the reST sources are included in the HTML build as _sources/name.
+html_copy_source = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# Tweak rendering
+def setup(app):
+    app.add_stylesheet('css/custom.css')

requirements/base.txt

@@ -16,3 +16,9 @@ django-stdimage >=4.1,<4.2  # https://github.com/codingjoe/django-stdimage
 django-tables2  # https://github.com/jieter/django-tables2
 django-tapeforms >=0.2,<0.3  # https://github.com/stephrdev/django-tapeforms
 django-cruditor >=1.3,<1.4  # https://github.com/moccu/django-cruditor
+
+# Documentation
+# ------------------------------------------------------------------------------
+sphinx
+sphinx-rtd-theme
+django-docs