replace mkdocs with sphinx/myst-parser for HTML documentation generation

nodiscc · nodiscc · commit db1532214e98 · 2023-10-05T15:01:34.000+02:00
- fixes #1451 - tools/.gitattributes: exclude doc/conf.py and doc/requirements.txt from zip exports - tools/doc/sphinx: suppress myst.xref_missing warnings caused by executablebooks/MyST-Parser#564 - dockerfile: use makefile/sphinx instead of mkdocs to build HTML documentation - dockerfile: add bash to the docs build container (make: bash: No such file or directory) - tools/doc/readthedocs: force use of python 3.11 (readthedocs ERROR: No matching distribution found for sphinx==7.1.0) - tools/doc/readthedocs: add all required configuration variables https://docs.readthedocs.io/en/latest/config-file/v2.html#build-os - tools/doc/readthedocs: override build commands to allow the source directory to be different from the conf.py directory (https://docs.readthedocs.io/en/stable/config-file/v2.html#build-commands, readthedocs/readthedocs.org#1543) - tools/doc/readthedocs: manually set output directory (readthedocs ERROR: No _readthedocs/html folder was created during this build.) - doc: replace all references to mkdocs with sphinx
diff --git a/.gitattributes b/.gitattributes
@@ -40,6 +40,7 @@ Dockerfile*       export-ignore
 Doxyfile          export-ignore
 Makefile          export-ignore
 node_modules/     export-ignore
-mkdocs.yml        export-ignore
+doc/conf.py       export-ignore
+doc/requirements.txt export-ignore
 phpunit.xml       export-ignore
 tests/            export-ignore
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -5,11 +5,19 @@
 # Required
 version: 2
 
-# Build documentation with MkDocs
-mkdocs:
-  configuration: mkdocs.yml
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+  builder: html
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design
+    - sphinx-build -b html -c doc/ doc/md/ _readthedocs/html/
 
-# Optionally set the version of Python and requirements required to build your docs
-# https://github.com/rtfd/readthedocs.org/issues/5250
 python:
-  version: 3.5
+  install:
+    - requirements: doc/requirements.txt
diff --git a/Dockerfile b/Dockerfile
@@ -4,9 +4,8 @@
 FROM python:3-alpine as docs
 ADD . /usr/src/app/shaarli
 RUN cd /usr/src/app/shaarli \
-    && apk add --no-cache gcc musl-dev \
-    && pip install --no-cache-dir mkdocs \
-    && mkdocs build --clean
+    && apk add --no-cache gcc musl-dev make bash \
+    && make htmldoc
 
 # Stage 2:
 # - Resolve PHP dependencies with Composer
diff --git a/Makefile b/Makefile
@@ -159,13 +159,13 @@ generate_authors:
 phpdoc: clean
 	@docker run --rm -v $(PWD):/data -u `id -u`:`id -g` phpdoc/phpdoc
 
-### generate HTML documentation from Markdown pages with MkDocs
+### generate HTML documentation from Markdown pages with Sphinx
 htmldoc:
 	python3 -m venv venv/
 	bash -c 'source venv/bin/activate; \
 	pip install wheel; \
-	pip install mkdocs; \
-	mkdocs build --clean'
+	pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design; \
+	sphinx-build -b html -c doc/ doc/md/ doc/html/'
 	find doc/html/ -type f -exec chmod a-x '{}' \;
 	rm -r venv
 
diff --git a/doc/conf.py b/doc/conf.py
@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+project = 'shaarli'
+author = 'shaarli community'
+version = '0.12.2'
+release = '0.12.2'
+copyright = '2011-2023, the shaarli community'
+language = 'en'
+html_title = 'Shaarli documentation'
+html_theme = 'furo'
+html_show_sphinx = False
+html_show_search_summary = True
+html_copy_source = False
+html_show_copyright = True
+html_use_opensearch = 'https://shaarli.readthedocs.io/'
+html_logo = 'md/images/doc-logo.svg'
+html_favicon = 'md/images/icon.png'
+extensions = ['myst_parser', 'sphinx_design']
+source_suffix = ['.md']
+templates_path = ['_templates']
+exclude_patterns = []
+suppress_warnings = ["myst.xref_missing"]
+
+# myst-parser configuration (https://myst-parser.readthedocs.io/en/latest/configuration.html)
+myst_enable_extensions = ['fieldlist']
+myst_html_meta = {
+    "description lang=en": "The personal, minimalist, super fast, database-free bookmarking service",
+    "charset": "UTF-8"
+}
+
+# theme configuration (https://pradyunsg.me/furo/customisation/)
+html_theme_options = {
+    "top_of_page_button": None,
+    # "announcement": "Example announcement!"
+    "source_repository": "https://github.com/shaarli/shaarli",
+    "source_branch": "master",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/shaarli/shaarli",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ]
+}
diff --git a/doc/custom_theme/main.html b/doc/custom_theme/main.html
diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md
@@ -161,7 +161,7 @@ See [`.github/workflows/`](https://github.com/shaarli/Shaarli/tree/master/.githu
 
 ### Documentation
 
-[mkdocs](https://www.mkdocs.org/) is used to convert markdown documentation to HTML pages. The [public documentation](https://shaarli.readthedocs.io/en/master/) website is rendered and hosted by [readthedocs.org](https://readthedocs.org/). A copy of the documentation is also included in prebuilt [release archives](https://github.com/shaarli/Shaarli/releases) (`doc/html/` path in your Shaarli installation). To generate the HTML documentation locally, install a recent version of Python `setuptools` and run `make doc`.
+[Sphinx](https://www.sphinx-doc.org/en/master/) is used to convert markdown documentation to HTML pages. The [public documentation](https://shaarli.readthedocs.io/en/master/) website is rendered and hosted by [readthedocs.org](https://readthedocs.org/). A copy of the documentation is also included in prebuilt [release archives](https://github.com/shaarli/Shaarli/releases) (`doc/html/` path in your Shaarli installation). To generate the HTML documentation locally, run `make htmldoc`.
 
 
 ## Static analysis
diff --git a/doc/md/index.md b/doc/md/index.md
@@ -13,7 +13,23 @@ Visit the pages in the sidebar to find information on how to setup, use, configu
 
 [![](https://i.imgur.com/8wEBRSG.png)](https://i.imgur.com/WWPfSj0.png) [![](https://i.imgur.com/93PpLLs.png)](https://i.imgur.com/V09kAQt.png) [![](https://i.imgur.com/rrsjWYy.png)](https://i.imgur.com/TZzGHMs.png) [![](https://i.imgur.com/8iRzHfe.png)](https://i.imgur.com/sfJJ6NT.png) [![](https://i.imgur.com/GjZGvIh.png)](https://i.imgur.com/QsedIuJ.png) [![](https://i.imgur.com/TFZ9PEq.png)](https://i.imgur.com/KdtF8Ll.png) [![](https://i.imgur.com/uICDOle.png)](https://i.imgur.com/27wYsbC.png) [![](https://i.imgur.com/tVvD3gH.png)](https://i.imgur.com/zGF4d6L.jpg)
 
-
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+Server-configuration.md
+Installation.md
+Reverse-proxy.md
+Docker.md
+Shaarli-configuration.md
+Usage.md
+Backup-and-restore.md
+Upgrade-and-migration.md
+Community-and-related-software.md
+Plugins.md
+REST-API.md
+Troubleshooting.md
+```
 
 ## Demo
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -0,0 +1,4 @@
+sphinx==7.1.0
+furo==2023.7.26
+myst-parser
+sphinx-design
diff --git a/mkdocs.yml b/mkdocs.yml
