From bc18398f3c04c7274a8db8c751c1c52cc426aabe Mon Sep 17 00:00:00 2001 From: Keshav Priyadarshi Date: Thu, 26 Sep 2024 23:01:00 +0530 Subject: [PATCH 1/2] Place the RST docs under docs/source - Use the docs structure provided by the skeleton Signed-off-by: Keshav Priyadarshi --- Makefile | 6 +++--- docs/Makefile | 12 ++++++++++-- docs/changelog.rst | 1 - docs/make.bat | 16 ++++++++++++++-- docs/scripts/doc8_style_check.sh | 2 +- docs/scripts/sphinx_build_link_check.sh | 2 +- docs/{ => source}/application-settings.rst | 0 docs/source/changelog.rst | 1 + docs/{ => source}/command-line-interface.rst | 0 docs/{ => source}/conf.py | 12 ++++++++++++ docs/{ => source}/contributing.rst | 0 docs/{ => source}/data-models.rst | 0 docs/{ => source}/faq.rst | 0 docs/{ => source}/index.rst | 0 docs/{ => source}/installation.rst | 0 docs/{ => source}/introduction.rst | 0 docs/{ => source}/rest-api.rst | 0 docs/{ => source}/schemas.rst | 4 ++-- docs/{ => source}/user-interface.rst | 0 19 files changed, 44 insertions(+), 12 deletions(-) delete mode 100644 docs/changelog.rst rename docs/{ => source}/application-settings.rst (100%) create mode 100644 docs/source/changelog.rst rename docs/{ => source}/command-line-interface.rst (100%) rename docs/{ => source}/conf.py (90%) rename docs/{ => source}/contributing.rst (100%) rename docs/{ => source}/data-models.rst (100%) rename docs/{ => source}/faq.rst (100%) rename docs/{ => source}/index.rst (100%) rename docs/{ => source}/installation.rst (100%) rename docs/{ => source}/introduction.rst (100%) rename docs/{ => source}/rest-api.rst (100%) rename docs/{ => source}/schemas.rst (62%) rename docs/{ => source}/user-interface.rst (100%) diff --git a/Makefile b/Makefile index 944d938..40647a8 100644 --- 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 index ed88099..156c18d 100644 --- 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) \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst deleted file mode 100644 index 565b052..0000000 --- a/docs/changelog.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CHANGELOG.rst diff --git a/docs/make.bat b/docs/make.bat index 922152e..7ca0d15 100644 --- 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 index 8a8ac8c..922097b 100755 --- 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 index 5833e0f..3b27156 100755 --- 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 b/docs/source/application-settings.rst similarity index 100% rename from docs/application-settings.rst rename to docs/source/application-settings.rst diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..09929fe --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../CHANGELOG.rst diff --git a/docs/command-line-interface.rst b/docs/source/command-line-interface.rst similarity index 100% rename from docs/command-line-interface.rst rename to docs/source/command-line-interface.rst diff --git a/docs/conf.py b/docs/source/conf.py similarity index 90% rename from docs/conf.py rename to docs/source/conf.py index aaca23b..de086fe 100644 --- a/docs/conf.py +++ b/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 b/docs/source/contributing.rst similarity index 100% rename from docs/contributing.rst rename to docs/source/contributing.rst diff --git a/docs/data-models.rst b/docs/source/data-models.rst similarity index 100% rename from docs/data-models.rst rename to docs/source/data-models.rst diff --git a/docs/faq.rst b/docs/source/faq.rst similarity index 100% rename from docs/faq.rst rename to docs/source/faq.rst diff --git a/docs/index.rst b/docs/source/index.rst similarity index 100% rename from docs/index.rst rename to docs/source/index.rst diff --git a/docs/installation.rst b/docs/source/installation.rst similarity index 100% rename from docs/installation.rst rename to docs/source/installation.rst diff --git a/docs/introduction.rst b/docs/source/introduction.rst similarity index 100% rename from docs/introduction.rst rename to docs/source/introduction.rst diff --git a/docs/rest-api.rst b/docs/source/rest-api.rst similarity index 100% rename from docs/rest-api.rst rename to docs/source/rest-api.rst diff --git a/docs/schemas.rst b/docs/source/schemas.rst similarity index 62% rename from docs/schemas.rst rename to docs/source/schemas.rst index 2c96031..c911892 100644 --- a/docs/schemas.rst +++ b/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 b/docs/source/user-interface.rst similarity index 100% rename from docs/user-interface.rst rename to docs/source/user-interface.rst From 887fbd41bba2bd56825bf6a62423b8dd5a81b0f3 Mon Sep 17 00:00:00 2001 From: Keshav Priyadarshi Date: Thu, 26 Sep 2024 23:10:16 +0530 Subject: [PATCH 2/2] Fix typos in introduction Signed-off-by: Keshav Priyadarshi --- docs/source/introduction.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 69ddf5e..6090e05 100644 --- a/docs/source/introduction.rst +++ b/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.