From db1532214e98e76cfd8c6b39c2837c32eaaa09d8 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 28 Aug 2023 09:33:33 +0200 Subject: [PATCH] replace mkdocs with sphinx/myst-parser for HTML documentation generation - fixes https://github.com/shaarli/Shaarli/issues/1451 - tools/.gitattributes: exclude doc/conf.py and doc/requirements.txt from zip exports - tools/doc/sphinx: suppress myst.xref_missing warnings caused by https://github.com/executablebooks/MyST-Parser/issues/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, https://github.com/readthedocs/readthedocs.org/issues/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 --- .gitattributes | 3 ++- .readthedocs.yml | 20 +++++++++++----- Dockerfile | 5 ++-- Makefile | 6 ++--- doc/conf.py | 49 ++++++++++++++++++++++++++++++++++++++ doc/custom_theme/main.html | 23 ------------------ doc/md/dev/Development.md | 2 +- doc/md/index.md | 18 +++++++++++++- doc/requirements.txt | 4 ++++ mkdocs.yml | 43 --------------------------------- 10 files changed, 92 insertions(+), 81 deletions(-) create mode 100644 doc/conf.py delete mode 100644 doc/custom_theme/main.html create mode 100644 doc/requirements.txt delete mode 100644 mkdocs.yml diff --git a/.gitattributes b/.gitattributes index 9a92bc37d..7991f9635 100644 --- 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 index 09e5a6a5f..bdbed8e52 100644 --- 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 \ No newline at end of file + install: + - requirements: doc/requirements.txt diff --git a/Dockerfile b/Dockerfile index aab91ca32..8e995a6ad 100644 --- 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 index dcf5d92d0..8f8d335b3 100644 --- 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 new file mode 100644 index 000000000..080115020 --- /dev/null +++ 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": """ + + + + """, + "class": "", + }, + ] +} diff --git a/doc/custom_theme/main.html b/doc/custom_theme/main.html deleted file mode 100644 index 96bb153e8..000000000 --- a/doc/custom_theme/main.html +++ /dev/null @@ -1,23 +0,0 @@ -{% extends "base.html" %} - -{# -The entry point for the ReadTheDocs Theme. - -Any theme customisations should override this file to redefine blocks defined in -the various templates. The custom theme should only need to define a main.html -which `{% extends "base.html" %}` and defines various blocks which will replace -the blocks defined in base.html and its included child templates. -#} - -{%- block site_meta %} - - - - -{%- if config.extra_css|length and 'media.readthedocs.org' not in config.extra_css[0] %} - -{%- endif %} - -{% if page and page.is_homepage %}{% endif %} -{% if config.site_author %}{% endif %} -{%- endblock %} diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md index 2b57e141e..6afbd0df2 100644 --- 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 index bc6df3cde..65e82b9b9 100644 --- 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 new file mode 100644 index 000000000..5ba9f9718 --- /dev/null +++ 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 deleted file mode 100644 index 550267582..000000000 --- a/mkdocs.yml +++ /dev/null @@ -1,43 +0,0 @@ -site_name: Shaarli Documentation -repo_url: https://github.com/shaarli/Shaarli -edit_uri: edit/master/doc/md -site_description: The personal, minimalist, super fast, database-free, bookmarking service -theme: - name: readthedocs - custom_dir: doc/custom_theme/ -docs_dir: doc/md -site_dir: doc/html -# Disable strict mode until ReadTheDocs provides up-to-date MkDocs settings: -# - https://github.com/shaarli/Shaarli/issues/1179 -# - https://github.com/rtfd/readthedocs.org/issues/4314 -# strict: true - -nav: -- Home: index.md -- Setup: - - Server configuration: Server-configuration.md - - Installation: Installation.md - - Docker: Docker.md - - Reverse Proxy: Reverse-proxy.md - - Backup and restore: Backup-and-restore.md - - Shaarli configuration: Shaarli-configuration.md - - Plugins: Plugins.md - - Upgrade and migration: Upgrade-and-migration.md -- Usage: - - Usage: Usage.md - - REST API: REST-API.md - - Community and Related software: Community-and-related-software.md -- Development: - - Development: dev/Development.md - - Versioning: dev/Versioning.md - - GnuPG signature: dev/GnuPG-signature.md - - Plugin System: dev/Plugin-system.md - - Translations: dev/Translations.md - - Release Shaarli: dev/Release-Shaarli.md - - Theming: dev/Theming.md - - Unit tests: dev/Unit-tests.md -- Troubleshooting: Troubleshooting.md - -markdown_extensions: - - toc: - permalink: "#"