Merge pull request #21 from aboutcode-org/fix-failing-rtd-build

Fix Failing Read the Docs Build
aboutcode-org · Sep 26, 2024 · 3e8898e · 3e8898e
2 parents 804843a + 887fbd4
commit 3e8898e
Show file tree

Hide file tree

Showing 19 changed files with 47 additions and 15 deletions.
diff --git a/Makefile b/Makefile
@@ -60,7 +60,7 @@ black:
 
 doc8:
 	@echo "-> Run doc8 validation"
-	@${ACTIVATE} doc8 --max-line-length 100 --ignore-path docs/build/ --quiet docs/
+	@${ACTIVATE} doc8 --max-line-length 100 --ignore-path docs/_build/ --quiet docs/
 
 valid: isort black doc8
 
@@ -95,8 +95,8 @@ test:
 	@${ACTIVATE} pytest -vvs
 
 docs:
-	rm -rf docs/build/
-	@${ACTIVATE} sphinx-build docs/ docs/build/
+	rm -rf docs/_build/
+	@${ACTIVATE} sphinx-build docs/source docs/_build/
 
 postgresdb:
 	@echo "-> Configure PostgreSQL database"

diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+SPHINXAUTOBUILD = sphinx-autobuild
+SOURCEDIR     = source
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
@@ -14,7 +15,14 @@ help:
 
 .PHONY: help Makefile
 
+# Run the development server using sphinx-autobuild
+docs:
+	@echo
+	@echo "Starting up the docs server..."
+	@echo
+	$(SPHINXAUTOBUILD) --port 8000 --watch ${SOURCEDIR} $(SOURCEDIR) "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
 # 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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/changelog.rst b/docs/changelog.rst
diff --git a/docs/make.bat b/docs/make.bat
@@ -7,11 +7,16 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
-set BUILDDIR=_build
+if "%SPHINXAUTOBUILD%" == "" (
+	set SPHINXAUTOBUILD=sphinx-autobuild
+)
+set SOURCEDIR=source
+set BUILDDIR=build
 
 if "%1" == "" goto help
 
+if "%1" == "docs" goto docs
+
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -28,6 +33,13 @@ if errorlevel 9009 (
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
+:docs
+@echo
+@echo Starting up the docs server...
+@echo
+%SPHINXAUTOBUILD% --port 8000 --watch %SOURCEDIR% %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+goto end
+
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 

diff --git a/docs/scripts/doc8_style_check.sh b/docs/scripts/doc8_style_check.sh
@@ -2,4 +2,4 @@
 # halt script on error
 set -e
 # Check for Style Code Violations
-doc8 --max-line-length 100 --ignore D000 --ignore-path build --quiet .
+doc8 --max-line-length 100 source --ignore D000 --quiet
diff --git a/docs/scripts/sphinx_build_link_check.sh b/docs/scripts/sphinx_build_link_check.sh
@@ -2,4 +2,4 @@
 # halt script on error
 set -e
 # Build locally, and then check links
-sphinx-build -E -W -b linkcheck . build
+sphinx-build -E -W -b linkcheck source build
diff --git a/docs/application-settings.rst → docs/source/application-settings.rst b/docs/application-settings.rst → docs/source/application-settings.rst
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst
diff --git a/docs/command-line-interface.rst → docs/source/command-line-interface.rst b/docs/command-line-interface.rst → docs/source/command-line-interface.rst
diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
@@ -75,6 +75,18 @@
 
 master_doc = "index"
 
+html_context = {
+    "display_github": True,
+    "github_user": "aboutcode-org",
+    "github_repo": "federatedcode",
+    "github_version": "main",  # branch
+    "conf_py_path": "/docs/source/",  # path in the checkout to the docs root
+}
+
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = True
+
 # user starts in light mode (Default Mode)
 default_dark_mode = False
 

diff --git a/docs/contributing.rst → docs/source/contributing.rst b/docs/contributing.rst → docs/source/contributing.rst
diff --git a/docs/data-models.rst → docs/source/data-models.rst b/docs/data-models.rst → docs/source/data-models.rst
diff --git a/docs/faq.rst → docs/source/faq.rst b/docs/faq.rst → docs/source/faq.rst
diff --git a/docs/index.rst → docs/source/index.rst b/docs/index.rst → docs/source/index.rst
diff --git a/docs/installation.rst → docs/source/installation.rst b/docs/installation.rst → docs/source/installation.rst
diff --git a/docs/introduction.rst → docs/source/introduction.rst b/docs/introduction.rst → docs/source/introduction.rst
@@ -30,7 +30,7 @@ sharing of curated metadata along with air-gapped, local usage to preserve priva
 confidentiality.
 
 Because FederatedCode is decentralized and federated, it promotes sharing without having a single
-centralized ownehsip and point of control.
+centralized ownership and point of control.
 
 FederatedCode's distributed metadata collection process includes metadata crawling, curation and
 sharing, and its application to open source software package origin, license and vulnerabilities.
@@ -45,8 +45,8 @@ What is FederatedCode?
 
 - A system to store versioned metadata as structure text (JSON, YAML) in multiple Git repositories
   structured to enable direct content retrieval using a Package URL (PURL),
-- A series of utilities to synchronize AboutCode dabatases with these versioned metadata, and
+- A series of utilities to synchronize AboutCode databases with these versioned metadata, and
 - A system to publish package-centric events such as the release of a new package version, the
-  publication of a vulnerability, the availability of detailes scans, analysis and SBOMs using
+  publication of a vulnerability, the availability of detail scans, analysis and SBOMs using
   publish/subscribe mechanism over ActivityPub. This further enables distributed discussions and
   curation of the data, in the open.
diff --git a/docs/rest-api.rst → docs/source/rest-api.rst b/docs/rest-api.rst → docs/source/rest-api.rst
diff --git a/docs/schemas.rst → docs/source/schemas.rst b/docs/schemas.rst → docs/source/schemas.rst
@@ -7,10 +7,10 @@ This section is a collection of JSON schemas for the FederatedCode Data.
 
 Package
 -------
-.. jsonschema:: ../schemas/package.schema.json
+.. jsonschema:: ../../schemas/package.schema.json
 
 
 
 Vulnerability
 --------------------
-.. jsonschema:: ../schemas/vulnerability.schema.json
+.. jsonschema:: ../../schemas/vulnerability.schema.json
diff --git a/docs/user-interface.rst → docs/source/user-interface.rst b/docs/user-interface.rst → docs/source/user-interface.rst