docs: Initial docs structure and infrastructure

.github/workflows/codespell.yml

@@ -27,4 +27,5 @@ jobs:
             ./etc/leapp/files/device_driver_deprecation_data.json,\
             ./etc/leapp/files/pes-events.json,\
             ./etc/leapp/files/repomap.json,\
-            ./repos/system_upgrade/common/files/prod-certs"
+            ./repos/system_upgrade/common/files/prod-certs,\
+            ./docs/source/_static"

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.10"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+     - requirements: docs/requirements-docs.txt

Makefile

@@ -358,7 +358,7 @@ lint:
 
 	if [[  "`git rev-parse --abbrev-ref HEAD`" != "$(MASTER_BRANCH)" ]] && [[ -n "`git diff $(MASTER_BRANCH) --name-only --diff-filter AMR`" ]]; then \
 		. $(VENVNAME)/bin/activate; \
-		git diff $(MASTER_BRANCH) --name-only --diff-filter AMR | xargs isort -c --diff || \
+		git diff $(MASTER_BRANCH) --name-only --diff-filter AMR | grep -v "^docs/" | xargs isort -c --diff || \
 		{ \
 			echo; \
 			echo "------------------------------------------------------------------------------"; \
@@ -370,7 +370,7 @@ lint:
 
 lint_fix:
 	. $(VENVNAME)/bin/activate; \
-	git diff $(MASTER_BRANCH) --name-only --diff-filter AMR | xargs isort && \
+	git diff $(MASTER_BRANCH) --name-only --diff-filter AMR | grep -v "^docs/" | xargs isort && \
 	echo "--- isort inplace fixing done. ---;"
 
 test_no_lint:

docs/Makefile

@@ -0,0 +1,31 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXAUTOBUILD = sphinx-autobuild
+SPHINXPROJ    = Leapp repository
+SOURCEDIR     = source
+BUILDDIR      = build
+
+all: clean html
+
+help:
+	@source venv/bin/activate && \
+	$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+livehtml:
+	@source venv/bin/activate && \
+	$(SPHINXAUTOBUILD) --watch ../repos --watch ../commands "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(0)
+
+# Prepare virtualenv similar to the environment used during build on Read The Docs and install required packages
+env:
+	@PY_VER=$$(sed -n -e 's/^\s*python:\s"\(.*\)"/\1/p' ../.readthedocs.yaml); \
+	rm -fr ./venv; \
+	virtualenv venv --python=python$$PY_VER && \
+	source venv/bin/activate && \
+	pip install -r requirements-docs.txt;
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@source venv/bin/activate && \
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: all help Makefile env

docs/requirements-docs.txt

@@ -0,0 +1,7 @@
+sphinx==7.2.6
+sphinx_rtd_theme
+sphinxcontrib-jquery
+docutils
+CommonMark
+myst-parser
+sphinx-autobuild