Meta doc ¶
Head project : tuto_devops ¶
Inspiration : sphinx-blogging de Chris Holdgraf ¶
Gitlab project ¶
See also
Issues ¶
Pipelines ¶
Sphinx theme : sphinx_book_theme ¶
import sphinx
liste_full = [
"globaltoc.html",
html_theme = "sphinx_book_theme"
copyright = f"2018-{now.year}, {author}, Creative Commons CC BY-NC-SA 3.0. Built with sphinx {sphinx.__version__} Python {platform.python_version()} {html_theme=}"
root directory ¶
$ ls -als
$ ls -als
total 192
4 drwxr-xr-x 14 4096 nov. 12 10:48 .
4 drwxr-xr-x 28 4096 nov. 11 11:09 ..
4 drwxr-xr-x 5 4096 avril 24 2020 api
4 drwxr-xr-x 3 4096 avril 24 2020 browsers
4 drwxr-xr-x 4 4096 août 31 15:09 _build
4 -rw-r--r-- 1 1512 sept. 17 14:13 conf.py
4 -rw-r--r-- 1 97 nov. 12 10:48 feed.xml
4 drwxr-xr-x 8 4096 nov. 12 10:49 .git
4 -rw-r--r-- 1 355 avril 24 2020 .gitattributes
4 -rw-r--r-- 1 119 avril 24 2020 .gitignore
4 -rw-r--r-- 1 250 oct. 7 10:36 .gitlab-ci.yml
4 drwxr-xr-x 2 4096 avril 24 2020 glossaires
4 drwxr-xr-x 11 4096 nov. 12 10:44 http
4 drwxr-xr-x 2 4096 oct. 19 08:05 index
4 -rw-r--r-- 1 859 juil. 9 16:20 index.rst
4 -rw-r--r-- 1 752 avril 24 2020 make.bat
4 -rw-r--r-- 1 1153 nov. 11 18:21 Makefile
4 drwxr-xr-x 3 4096 nov. 12 10:48 meta
4 drwxr-xr-x 4 4096 août 31 14:47 news
4 drwxr-xr-x 4 4096 avril 24 2020 people
88 -rw-r--r-- 1 88469 nov. 12 10:48 poetry.lock
4 -rw-rw-rw- 1 1346 nov. 11 18:32 .pre-commit-config.yaml
4 -rw-r--r-- 1 498 oct. 27 16:30 pyproject.toml
4 -rw-r--r-- 1 214 avril 24 2020 README.md
4 -rw-r--r-- 1 542 oct. 2 12:58 requirements.txt
4 drwxr-xr-x 6 4096 avril 24 2020 servers
4 drwxr-xr-x 3 4096 avril 24 2020 tutorials
pyproject.toml ¶
1[tool.poetry]
2name = "tuto_http"
3version = "0.1.0"
4description = "Tuto HTTP"
5authors = ["Noam <noamsw@pm.me>"]
6
7[tool.poetry.dependencies]
8python = "^3.11"
9sphinx-material = "*"
10sphinx-markdown-tables = "*"
11sphinx-copybutton = "*"
12sphinx-panels = "*"
13sphinx-tabs = "*"
14autoclasstoc = "*"
15Sphinx = "*"
16myst-parser = "*"
17
18[tool.poetry.dev-dependencies]
19
20[build-system]
21requires = ["poetry-core>=1.0.0"]
22build-backend = "poetry.core.masonry.api"
conf.py ¶
1# Configuration file for the Sphinx documentation builder.
2#
3# This file only contains a selection of the most common options. For a full
4# list see the documentation:
5# http://www.sphinx-doc.org/en/master/config
6# -- Path setup --------------------------------------------------------------
7# If extensions (or modules to document with autodoc) are in another directory,
8# add these directories to sys.path here. If the directory is relative to the
9# documentation root, use os.path.abspath to make it absolute, like shown here.
10#
11# import os
12# import sys
13# sys.path.insert(0, os.path.abspath('.'))
14import platform
15from datetime import datetime
16from zoneinfo import ZoneInfo
17
18import sphinx
19import sphinx_material
20
21# If extensions (or modules to document with autodoc) are in another directory,
22# add these directories to sys.path here. If the directory is relative to the
23# documentation root, use os.path.abspath to make it absolute, like shown here.
24# sys.path.insert(0, os.path.abspath("./src"))
25
26
27project = "Tuto HTTP"
28html_title = project
29
30author = f"DevOps people"
31html_logo = "images/http_logo.png"
32html_favicon = "images/http_logo.png"
33release = "0.1.0"
34now = datetime.now(tz=ZoneInfo("Europe/Paris"))
35version = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H ({now.tzinfo})"
36today = version
37
38extensions = [
39 "sphinx.ext.autodoc",
40 "sphinx.ext.doctest",
41 "sphinx.ext.extlinks",
42 "sphinx.ext.intersphinx",
43 "sphinx.ext.todo",
44 "sphinx.ext.mathjax",
45 "sphinx.ext.viewcode",
46 "myst_parser",
47 "sphinx_markdown_tables",
48 "sphinx_copybutton",
49]
50autosummary_generate = True
51autoclass_content = "class"
52
53# Add any paths that contain templates here, relative to this directory.
54templates_path = ["_templates"]
55exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
56html_static_path = ["_static"]
57html_show_sourcelink = True
58html_sidebars = {
59 "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
60}
61extensions.append("sphinx_material")
62html_theme_path = sphinx_material.html_theme_path()
63html_context = sphinx_material.get_html_context()
64html_theme = "sphinx_material"
65
66extensions.append("sphinx.ext.intersphinx")
67intersphinx_mapping = {
68 "project": ("https://gdevops.gitlab.io/tuto_project/", None),
69 "python": ("https://gdevops.gitlab.io/tuto_git/", None),
70 "django": ("https://gdevops.gitlab.io/tuto_django/", None),
71 "web": ("https://gdevops.gitlab.io/tuto_web/", None),
72 "sysops": ("https://gdevops.gitlab.io/tuto_sysops/", None),
73 "javascript": ("https://gdevops.gitlab.io/tuto_javascript/", None),
74 "tuto_htmx": ("https://gdevops.gitlab.io/tuto_htmx/", None),
75 "asgi": ("https://asgi.readthedocs.io/en/latest/", None),
76 "webframeworks": ("https://gdevops.gitlab.io/tuto_webframeworks/", None),
77 "languages": ("https://gdevops.gitlab.io/tuto_languages/", None),
78 "programming": ("https://gdevops.gitlab.io/tuto_programming/", None),
79}
80extensions.append("sphinx.ext.todo")
81todo_include_todos = True
82
83extensions += [
84 "sphinx_panels",
85]
86# autoclasstoc + napoleon + autodoc
87# https://autoclasstoc.readthedocs.io/en/latest/basic_usage.html
88extensions += [
89 "autoclasstoc",
90 "sphinx.ext.napoleon",
91 "sphinx.ext.autodoc",
92 "sphinx.ext.autosummary",
93 "sphinx.ext.viewcode",
94]
95autodoc_default_options = {
96 "members": True,
97 "special-members": True,
98 "private-members": True,
99 "inherited-members": True,
100 "undoc-members": True,
101 "exclude-members": "__weakref__",
102}
103
104# material theme options (see theme.conf for more information)
105# https://gitlab.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf
106# Colors
107# The theme color for mobile browsers. Hex color.
108# theme_color = #3f51b5
109# Primary colors:
110# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
111# teal, green, light-green, lime, yellow, amber, orange, deep-orange,
112# brown, grey, blue-grey, white
113# Accent colors:
114# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
115# teal, green, light-green, lime, yellow, amber, orange, deep-orange
116# color_accent = blue
117# color_primary = blue-grey
118
119# material theme options (see theme.conf for more information)
120html_theme_options = {
121 "base_url": "https://gdevops.gitlab.io/tuto_http/",
122 "repo_url": "https://gitlab.com/gdevops/tuto_http",
123 "repo_name": project,
124 "html_minify": False,
125 "html_prettify": True,
126 "css_minify": True,
127 "repo_type": "gitlab",
128 "globaltoc_depth": -1,
129 "color_primary": "green",
130 "color_accent": "cyan",
131 "theme_color": "#2196f3",
132 "nav_title": f"{project} ({today})",
133 "master_doc": False,
134 "nav_links": [
135 {
136 "href": "genindex",
137 "internal": True,
138 "title": "Index",
139 },
140 {
141 "href": "https://gdevops.gitlab.io/tuto_html/",
142 "internal": False,
143 "title": "HTML",
144 },
145 {
146 "href": "https://gdevops.gitlab.io/tuto_htmx/",
147 "internal": False,
148 "title": "htmx",
149 },
150 {
151 "href": "https://gdevops.gitlab.io/tuto_devops/",
152 "internal": False,
153 "title": "Tuto DevOps",
154 },
155 ],
156 "heroes": {
157 "index": "Tuto HTTP",
158 },
159 "table_classes": ["plain"],
160}
161
162
163language = "en"
164html_last_updated_fmt = ""
165
166todo_include_todos = True
167
168html_use_index = True
169html_domain_indices = True
170
171rst_prolog = """
172.. |Locust| image:: /images/locust_logo.png
173.. |LarsHolmberg| image:: /images/lars_holmberg.png
174"""
175
176copyright = f"2019-{now.year}, {author} Built with sphinx {sphinx.__version__} Python {platform.python_version()}"
gitlab-ci.yaml ¶
1---
2# https://hub.docker.com/_/python/
3image: python:3.11.0-slim-bullseye
4
5pages:
6 script:
7 - pip install -r requirements.txt
8 - sphinx-build -d _build/doctrees . _build/html
9 - mv _build/html public
10 artifacts:
11 paths:
12 - public
13 only:
14 - main
.pre-commit-config.yaml ¶
1---
2
3# .pre-commit-config.yaml
4# ========================
5#
6# pre-commit clean
7# pre-commit install
8# pre-commit install-hooks
9#
10# precommit hooks installation
11#
12# - pre-commit autoupdate
13#
14# - pre-commit run black
15#
16# continuous integration
17# ======================
18#
19# - pre-commit run --all-files
20#
21
22repos:
23 - repo: https://github.com/pre-commit/pre-commit-hooks
24 rev: v4.0.1
25 hooks:
26 - id: trailing-whitespace
27 - id: end-of-file-fixer
28 - id: check-yaml
29 - id: check-json
30 - id: fix-encoding-pragma
31 args: ['--remove']
32 - id: forbid-new-submodules
33 - id: mixed-line-ending
34 args: ['--fix=lf']
35 description: Forces to replace line ending by the UNIX 'lf' character.
36 # - id: pretty-format-json
37 # args: ['--no-sort-keys']
38 - id: check-added-large-files
39 args: ['--maxkb=500']
40 - id: no-commit-to-branch
41 args: [--branch, staging]
42
43 - repo: https://github.com/asottile/reorder_python_imports
44 rev: v2.6.0
45 hooks:
46 - id: reorder-python-imports
47
48 - repo: https://github.com/hadialqattan/pycln
49 rev: v1.1.0 # Possible releases: https://github.com/hadialqattan/pycln/tags
50 hooks:
51 - id: pycln
52 args: [--config=pyproject.toml]
Makefile ¶
1# Minimal makefile for Sphinx documentation
2#
3
4# You can set these variables from the command line.
5SPHINXOPTS =
6SPHINXBUILD = sphinx-build
7SPHINXPROJ = Tutopython
8SOURCEDIR = .
9BUILDDIR = _build
10
11THIS_MAKEFILE := $(lastword $(MAKEFILE_LIST))
12
13# Put it first so that "make" without argument is like "make help".
14help:
15 @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16 @echo " "
17 @echo "Targets:"
18 @echo " "
19 @echo "- make check_all"
20 @echo "- make req"
21 @echo "- make updatetools"
22 @echo "- make update"
23 @echo "- make clearcache"
24 @echo " "
25
26clearcache:
27 poetry cache clear --all pypi
28
29
30check_all:
31 pre-commit run --all-files
32
33req:
34 poetry env info --path
35 poetry show --tree
36 poetry check
37 poetry export -f requirements.txt --without-hashes > requirements.txt
38 cat requirements.txt
39
40update:
41 poetry update
42 @$(MAKE) -f $(THIS_MAKEFILE) req
43
44
45updatetools:
46 pre-commit autoupdate
47
48.PHONY: help Makefile
49
50# Catch-all target: route all unknown targets to Sphinx using the new
51# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
52%: Makefile
53 @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)