From 05e5008305e0c6833e27757e7a6f26bb33068751 Mon Sep 17 00:00:00 2001 From: Bartuccio Antoine Date: Fri, 9 Aug 2019 19:52:56 +0200 Subject: [PATCH] documentation: base structure for new documentation --- .gitignore | 1 + .readthedocs.yml | 18 ++++++ core/management/commands/documentation.py | 69 ++++++++++++++++++++++ doc/Makefile | 20 +++++++ doc/about/introduction.rst | 21 +++++++ doc/apps/core.rst | 7 +++ doc/apps/core/models.rst | 4 ++ doc/conf.py | 71 +++++++++++++++++++++++ doc/index.rst | 19 ++++++ doc/make.bat | 35 +++++++++++ requirements.txt | 4 ++ sith/settings.py | 2 +- 12 files changed, 270 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yml create mode 100644 core/management/commands/documentation.py create mode 100644 doc/Makefile create mode 100644 doc/about/introduction.rst create mode 100644 doc/apps/core.rst create mode 100644 doc/apps/core/models.rst create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/make.bat diff --git a/.gitignore b/.gitignore index 1859caab..c373aaee 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ sith/settings_custom.py sith/search_indexes/ .coverage coverage_report/ +doc/_build diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..87a19b4f --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,18 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the doc/ directory with Sphinx +sphinx: + configuration: doc/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +formats: all + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.6 + install: + - requirements: requirements.txt \ No newline at end of file diff --git a/core/management/commands/documentation.py b/core/management/commands/documentation.py new file mode 100644 index 00000000..9944b303 --- /dev/null +++ b/core/management/commands/documentation.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +# -*- coding:utf-8 -* +# +# Copyright 2019 +# - Sli +# +# Ce fichier fait partie du site de l'Association des Étudiants de l'UTBM, +# http://ae.utbm.fr. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License a published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later +# version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# this program; if not, write to the Free Sofware Foundation, Inc., 59 Temple +# Place - Suite 330, Boston, MA 02111-1307, USA. +# +# + +import os +import sys + +from http.server import test, CGIHTTPRequestHandler + +from django.core.management.base import BaseCommand +from django.conf import settings + + +class Command(BaseCommand): + help = "Generate Sphinx documentation and launch basic server" + + default_addr = "127.0.0.1" + default_port = "8080" + + def add_arguments(self, parser): + parser.add_argument( + "addrport", nargs="?", help="Optional port number, or ipaddr:port" + ) + + def handle(self, *args, **kwargs): + os.chdir("doc") + err = os.system("make html") + + if err != 0: + self.stdout.write("A build error occured, exiting") + sys.exit(err) + + os.chdir("_build/html") + addr = self.default_addr + port = self.default_port + if kwargs["addrport"]: + addrport = kwargs["addrport"].split(":") + + addr = addrport[0] + + if len(addrport) > 1: + port = addrport[1] + + if not port.isnumeric(): + self.stdout.write("%s is not a valid port" % (port,)) + sys.exit(0) + + test(HandlerClass=CGIHTTPRequestHandler, port=int(port), bind=addr) diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +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) diff --git a/doc/about/introduction.rst b/doc/about/introduction.rst new file mode 100644 index 00000000..f8dfdf7e --- /dev/null +++ b/doc/about/introduction.rst @@ -0,0 +1,21 @@ +Introduction au projet +====================== + + +Il y a longtemps, au début des années 2000, l'Association des Étudiants a mis en place un site internet qui n'a eu de +cesse d'évoluer au fil des ans. Grâce aux différents contributeurs qui s'y sont plongés, et qui ont pu y ajouter leurs +bouts de code plus ou moins utiles, le site possède désormais un ensemble de fonctionnalités impressionnant. + +De la comptabilité à la gestion de la laverie, en passant par le forum ou le Matmatronch', le site de l'AE prend +actuellement en charge la quasi totalité de la gestion de l'argent, et c'est là un de ses rôles les plus importants. + +Mais les vieilles technologies qu'il emploie, et l'entretien plus ou moins aléatoire qu'il a subit, en font un +outil très difficile à maintenir à l'heure actuelle, et le besoin d'une refonte s'imposait de plus en plus. + +Le choix de technologies récentes, maintenues, et éprouvées a donc été fait, et le développement a pu commencer dès +Novembre 2015, avec l'objectif d'une mise en production dans l'été 2016, au moins dans une version incluant +l'intégralité des fonctions liées à l'argent, qui sont les plus critiques. + +Soutenant les projets libres, j'ai décidé de placer le projet sous licence MIT, assurant ainsi une pérénité aux +source. Si quelqu'un dans le futur souhaite le relicencier sous GPL (ou autre licence plus restrictive que la MIT, voire +contagieuse), cela reste possible, mais je n'impose au départ que très peu de restrictions. \ No newline at end of file diff --git a/doc/apps/core.rst b/doc/apps/core.rst new file mode 100644 index 00000000..8d237032 --- /dev/null +++ b/doc/apps/core.rst @@ -0,0 +1,7 @@ +Documentation de core +===================== + +.. toctree:: + :maxdepth: 2 + + core/models.rst \ No newline at end of file diff --git a/doc/apps/core/models.rst b/doc/apps/core/models.rst new file mode 100644 index 00000000..0efaf3d1 --- /dev/null +++ b/doc/apps/core/models.rst @@ -0,0 +1,4 @@ +Classes liées aux utilisateurs +============================== + +.. autoclass:: core.models.User \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..322559b2 --- /dev/null +++ b/doc/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: +# 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 os +import sys +import django + +sys.path.insert(0, os.path.abspath("..")) +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sith.settings") + +# from django.conf import settings + +# settings.configure() +django.setup() + + +# -- Project information ----------------------------------------------------- + +project = "Sith AE UTBM" +copyright = ( + "2019, Bartuccio Antoine (Sli), Brunet Pierre (Krohpil), Jacquet Florent (Skia)" +) +author = "Bartuccio Antoine (Sli), Brunet Pierre (Krohpil), Jacquet Florent (Skia)" + + +# -- 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"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# 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 = ["_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"] + +# Disable contents.rst for forward compatibility +master_doc = "index" diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..80c1d55a --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,19 @@ +.. Sith AE UTBM documentation master file, created by + sphinx-quickstart on Thu Aug 8 19:24:14 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Bienvenue sur la documentation du Sith de l'AE +============================================== + +.. toctree:: + :maxdepth: 2 + :caption: À propos du projet: + + about/introduction + +.. toctree:: + :maxdepth: 3 + :caption: Documentation des apps: + + apps/core \ No newline at end of file diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..922152e9 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/requirements.txt b/requirements.txt index d5b5edd8..2679b73c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -20,3 +20,7 @@ python-dateutil pygraphviz sentry_sdk # mysqlclient + +# For documentation +Sphinx < 2.0 # To ensure compatibility with reathedocs +sphinx_rtd_theme diff --git a/sith/settings.py b/sith/settings.py index 50f95924..4b40dcac 100644 --- a/sith/settings.py +++ b/sith/settings.py @@ -577,7 +577,7 @@ SITH_EBOUTIC_HMAC_KEY = binascii.unhexlify( "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF" ) SITH_EBOUTIC_PUB_KEY = "" -with open("./sith/et_keys/pubkey.pem") as f: +with open(os.path.join(os.path.dirname(__file__), "et_keys/pubkey.pem")) as f: SITH_EBOUTIC_PUB_KEY = f.read() # Launderette variables