Sphinx Documentation Generator

Makefile

@@ -0,0 +1,41 @@
+# Python Training Course project makefile
+
+# base sphinx settings
+DOCS_SOURCE = docs
+DOCS_BUILDS = _build
+SPHINX_CONFIG = ./conf.py
+GETTEXT_BUILDS = $(DOCS_BUILDS)/gettext/$(LANGUAGE)
+HTML_BUILDS = $(DOCS_BUILDS)/html/$(LANGUAGE)
+LATEX_BUILDS = $(DOCS_BUILDS)/latex/$(LANGUAGE)
+
+# default internationalization settings
+SPHINXINTL_LANGUAGE ?= ua
+LANGUAGE ?= en
+
+# sphinx build settings
+BASE_BUILDER = sphinx-build -c . -q -D language=$(LANGUAGE)
+GETTEXT_BUILDER = $(BASE_BUILDER) -b gettext
+HTML_BUILDER = $(BASE_BUILDER) -b html
+LATEX_BUILDER = $(BASE_BUILDER) -b latex
+
+# documentation builds
+gettext :
+@$(GETTEXT_BUILDER) "$(DOCS_SOURCE)" "$(GETTEXT_BUILDS)"
+html :
+@$(HTML_BUILDER) "$(DOCS_SOURCE)" "$(HTML_BUILDS)"
+latex :
+@$(LATEX_BUILDER) "$(DOCS_SOURCE)" "$(LATEX_BUILD)"
+pdf : latex
+@make -C "$(LATEX_BUILDS)"
+
+# internationalization
+locales : gettext
+@sphinx-intl --config="$(SPHINX_CONFIG)" update -p "$(GETTEXT_BUILDS)"
+
+# clean up builds
+clean :
+@rm -rf $(DOCS_BUILDS)
+
+# export variables used by targets
+.EXPORT_ALL_VARIABLES :
+export SPHINXINTL_LANGUAGE = $(SPHINXINTL_LANGUAGE)

conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation generator
+
+import datetime
+import os
+import sys
+
+# Paths setup
+# ===========
+sys.path.insert(0, os.path.abspath("problem-sets/src"))
+
+# Project information
+# ===================
+project = "Python Training Course"
+now = datetime.datetime.now()
+project_copyright = f"{now:%Y}, {project}"
+authors = [
+ "Vladyslav Ponomaryov",
+ "Serhii Horodilov"
+]
+authors = ", ".join(authors)
+
+# General configuration
+# =====================
+master_doc = "index"
+extensions = [
+ "sphinx.ext.imgconverter",
+ "myst_parser",
+ "sphinx_rtd_theme",
+ "sphinxcontrib.mermaid",
+]
+source_suffix = {
+ ".rst": "restructuredtext",
+ ".txt": "restructuredtext",
+ ".md": "markdown",
+}
+needs_sphinx = "4.0"
+add_module_names = False
+
+# Options for internationalization
+# ================================
+language = "en"
+locale_dirs = ["_locales"]
+gettext_compact = True
+
+# Options for HTML output
+# =======================
+html_theme = "sphinx_rtd_theme"
+html_favicon = "assets/favicon.ico"
+
+# Options for LaTeX output
+# ========================
+latex_master_doc = master_doc
+latex_output = "PythonTrainingCourse.tex"
+latex_engine = "xelatex"
+latex_documents = [
+ (latex_master_doc, latex_output, project, authors, "manual", False),
+]

docs/index.txt

@@ -0,0 +1,15 @@
+.. master document
+
+###############################################################################
+ PYTHON TRAINING COURSE
+###############################################################################
+
+.. only:: html
+
+ This is a training course to master the Python programming language.
+ It covers topics from the very begging to some advanced themes.
+
+.. toctree::
+ :name: master_toc
+ :caption: Course Contents
+ :maxdepth: 1

requirements.txt

@@ -0,0 +1,33 @@
+alabaster==0.7.12
+Babel==2.10.3
+certifi==2022.6.15
+charset-normalizer==2.1.0
+click==8.1.3
+colorama==0.4.5
+docutils==0.17.1
+idna==3.3
+imagesize==1.4.1
+Jinja2==3.1.2
+markdown-it-py==2.1.0
+MarkupSafe==2.1.1
+mdit-py-plugins==0.3.0
+mdurl==0.1.1
+myst-parser==0.18.0
+packaging==21.3
+Pygments==2.12.0
+pyparsing==3.0.9
+pytz==2022.1
+PyYAML==6.0
+requests==2.28.1
+snowballstemmer==2.2.0
+Sphinx==5.0.2
+sphinx-intl==2.0.1
+sphinx-rtd-theme==1.0.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+typing_extensions==4.3.0
+urllib3==1.26.9