feat(doc): ajout d'une infra de documentation, servie en ligne via django-docs
parent
e293a84af9
commit
7562b786dc
|
@ -41,3 +41,4 @@ var/
|
|||
# builds
|
||||
styleguide/index.html
|
||||
benevalibre/static/
|
||||
docs/build/
|
||||
|
|
8
Makefile
8
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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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')),
|
||||
|
|
|
@ -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)
|
|
@ -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')
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue