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
This commit is contained in:
nodiscc
parent
c4d3e2d7ec
commit
db1532214e
3
.gitattributes
vendored
3
.gitattributes
vendored
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
6
Makefile
6
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
|
||||
|
||||
|
|
|
|||
49
doc/conf.py
Normal file
49
doc/conf.py
Normal file
|
|
@ -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": "",
|
||||
},
|
||||
]
|
||||
}
|
||||
|
|
@ -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 %}
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
{%- if config.extra_css|length and 'media.readthedocs.org' not in config.extra_css[0] %}
|
||||
<meta name="robots" content="noindex, nofollow">
|
||||
{%- endif %}
|
||||
|
||||
{% if page and page.is_homepage %}<meta name="description" content="{{ config.site_description }}">{% endif %}
|
||||
{% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %}
|
||||
{%- endblock %}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -13,7 +13,23 @@ Visit the pages in the sidebar to find information on how to setup, use, configu
|
|||
|
||||
[](https://i.imgur.com/WWPfSj0.png) [](https://i.imgur.com/V09kAQt.png) [](https://i.imgur.com/TZzGHMs.png) [](https://i.imgur.com/sfJJ6NT.png) [](https://i.imgur.com/QsedIuJ.png) [](https://i.imgur.com/KdtF8Ll.png) [](https://i.imgur.com/27wYsbC.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
|
||||
|
||||
|
|
|
|||
4
doc/requirements.txt
Normal file
4
doc/requirements.txt
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
sphinx==7.1.0
|
||||
furo==2023.7.26
|
||||
myst-parser
|
||||
sphinx-design
|
||||
43
mkdocs.yml
43
mkdocs.yml
|
|
@ -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: "#"
|
||||
Loading…
Reference in a new issue