📔 Improve Sphinx config

backend/Backend.iml

@@ -21,6 +21,7 @@
       <sourceFolder url="file://$MODULE_DIR$/../docs/source" isTestSource="false" />
       <sourceFolder url="file://$MODULE_DIR$/../docs/source/_static" type="java-resource" />
       <excludeFolder url="file://$MODULE_DIR$/../docs/build" />
+      <excludeFolder url="file://$MODULE_DIR$/../docs/source/_extra" />
     </content>
     <orderEntry type="jdk" jdkName="Poetry (backend) (3)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />

docs/source/conf.py

@@ -1,78 +1,148 @@
-# Configuration file for the Sphinx documentation builder.
+# Customized Sphinx configuration
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
 import datetime
 
 import pkg_resources
 
-# -- Project information -----------------------------------------------------
+# Project name
-
 project = 'Sophon'
+# Project author
 author = 'Stefano Pigozzi'
-copyright = f'{datetime.date.today().year}, {author}'
+# Project copyright
-release = pkg_resources.get_distribution("sophon").version
+project_copyright = f'{datetime.date.today().year}, {author}'
+# Project short version
+version = pkg_resources.get_distribution(project.lower()).version
+# Project long version
+release = pkg_resources.get_distribution(project.lower()).version
 
-# -- General configuration ---------------------------------------------------
+# Sphinx language
-
+language = "en"  # TODO: Change to it for thesis
-# Add any Sphinx extension module names here, as strings. They can be
+# Sphinx extensions
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
+    "sphinx.ext.autosectionlabel",  # TODO: Remove in thesis
-    "sphinx.ext.autosectionlabel",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
+# Source files encoding
-templates_path = ['_templates']
+source_encoding = "UTF-8"
+# Source file extensions
+source_suffix = {
+    ".rst": "restructuredtext",
+}
+# Source files parsers
+source_parsers = {}
 
-# List of patterns, relative to source directory, that match files and
+# The doc from which to start rendering
-# directories to ignore when looking for source files.
+root_doc = "index"
-# This pattern also affects html_static_path and html_extra_path.
+# Files to ignore when rendering
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    "build",
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
+# Sphinx template files
+templates_path = [
+    '_templates',
+]
+
+# Prologue of all rst files
+rst_prolog = ""
+# Epilogue of all rst files
+rst_epilog = ""
+
+# Default domain
+primary_domain = None
+# Default role
+default_role = None
 
 # Print warnings on the page
 keep_warnings = True
-
 # Display more warnings than usual
 nitpicky = True
 
-# -- Options for HTML output -------------------------------------------------
+# Intersphinx URLs
-
-# 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 = {
-    "style_nav_header_background": "#051836"
-}
-
-# 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']
-
-# -- Intersphinx options -----------------------------------------------------
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.8", None),
     "django": ("http://docs.djangoproject.com/en/3.2/", "http://docs.djangoproject.com/en/3.2/_objects/"),
     "docker": ("https://docker-py.readthedocs.io/en/stable/", None),
     "coloredlogs": ("https://coloredlogs.readthedocs.io/en/latest/", None),
 }
+# Manpages URL
+manpages_url = "https://man.archlinux.org/"
 
-# -- Automodule options ------------------------------------------------------
+# Autonumber figures
-
+numfig = False  # TODO: Set to true for thesis
-autodoc_default_options = {
+# Autonumeration formatting
-    'members': True,
+numfig_format = {
-    'member-order': 'bysource',
+    "figure": "Fig. %s",  # TODO: Translate in italian
-    'special-members': '__init__',
+    "table": "Table %s",  # TODO: Translate in italian
-    'undoc-members': True,
+    "code-block": "Listing %s",  # TODO: Translate in italian
-    'show-inheritance': False,
+    "section": "Section %s",  # TODO: Translate in italian
+}
+# Maximum depth for autonumeration
+numfig_secnum_depth = 2
+
+# HTML builder theme
+html_theme = 'sphinx_rtd_theme'
+# Configuration for the theme
+html_theme_options = {
+    "style_nav_header_background": "#051836",
+    "github_url": "https://github.com/Steffo99/sophon/tree/main/docs/source",
+}
+# Title of the HTML page
+html_title = f"{project}"
+# Short title of the HTML page
+html_short_title = f"{project}"
+# Path of the documentation static files
+html_static_path = [
+    "_static",
+]
+# Path of extra files to add to the build
+html_extra_path = [
+    "extra",
+]
+
+# LaTeX rendering engine to use
+latex_engine = "pdflatex"
+# LaTeX top level title type
+latex_toplevel_sectioning = "part"
+# LaTeX URLs rendering
+latex_show_urls = "footnote"
+# LaTeX theme
+latex_theme = "manual"  # TODO: I'm not sure between manual or howto
+
+latex_setup = {
+    "TitleColor": "{rgb}{0,0,0.08}",
+
+    "InnerLinkColor": "{rgb}{0.19,0.57,0.82}",
+    "OuterLinkColor": "{rgb}{0.19,0.57,0.82}",
+
+    "VerbatimBorderColor": "{rgb}{0.88,0.88,0.88}",
+    "VerbatimColor": "{rgb}{0.97,0.97,0.97}",
+
+    "noteBorderColor": "{rgb}{0.42,0.69,0.87}",
+    "importantBorderColor": "{rgb}{0.42,0.69,0.87}",
+
+    "hintBorderColor": "{rgb}{0.1,0.74,0.61}",
+    "tipBorderColor": "{rgb}{0.1,0.74,0.61}",
+
+    "warningBorderColor": "{rgb}{0.94,0.7,0.49}",
+    "warningBgColor": "{rgb}{1,0.93,0.8}",
+    "cautionBorderColor": "{rgb}{0.94,0.7,0.49}",
+    "cautionBgColor": "{rgb}{1,0.93,0.8}",
+    "attentionBorderColor": "{rgb}{0.94,0.7,0.49}",
+    "attentionBgColor": "{rgb}{1,0.93,0.8}",
+
+    "dangerBorderColor": "{rgb}{0.95,0.62,0.59}",
+    "dangerBgColor": "{rgb}{0.95,0.62,0.59}",
+    "errorBorderColor": "{rgb}{0.95,0.62,0.59}",
+    "errorBgColor": "{rgb}{0.95,0.62,0.59}",
+}
+latex_elements = {
+    # TODO: Set Times New Roman font
+    "papersize": "a4paper",
+    "pointsize": "12pt",
+    "sphinxsetup": ", ".join(f"{key}={value}" for key, value in latex_setup.items())
 }