Merge pull request #2025 from nodiscc/doc-sphinx

replace mkdocs with sphinx/myst-parser for HTML documentation generation, documentation improvements
shaarli · Oct 15, 2023 · ba21aa6 · ba21aa6
2 parents c4d3e2d + 484ee2b
commit ba21aa6
Show file tree

Hide file tree

Showing 29 changed files with 1,507 additions and 1,746 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -40,6 +40,8 @@ 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
+doc/html/.doctrees/  export-ignore
 phpunit.xml       export-ignore
 tests/            export-ignore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -93,11 +93,8 @@ jobs:
         with:
           python-version: 3.8
 
-      - name: Install dependencies
-        run: pip install mkdocs
-
       - name: Build documentation
-        run: mkdocs build --clean
+        run: make htmldoc
 
   trivy-repo:
     runs-on: ubuntu-latest

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/Community-and-related-software.md b/doc/md/Community-and-related-software.md
@@ -19,7 +19,7 @@ See [REST API](REST-API.md) for a list of official and community clients.
 - [disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
 - [emojione](https://github.com/immanuelfodor/emojione) by [@immanuelfodor](https://github.com/immanuelfodor) - Resurrected fork of the original emojione project
 - [favicons](https://github.com/trailjeep/shaarli-favicons) by [@trailjeep](https://github.com/trailjeep) - Shaarli plugin to add favicon/filetype icons to Shaares.
-- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
+- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](https://github.com/ericjuden): Adds Google Analytics tracking support
 - [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
 - [markdown-toolbar](https://github.com/immanuelfodor/shaarli-markdown-toolbar) by [@immanuelfodor](https://github.com/immanuelfodor) - Easily insert markdown syntax into the Description field when editing a Shaare.
 - [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related Shaares based on the number of identical tags.
@@ -32,28 +32,36 @@ See [REST API](REST-API.md) for a list of official and community clients.
 - [webhooks](https://gitlab.com/flow.gunso/shaarli-webhooks) by [@flow.gunso](https://gitlab.com/flow.gunso) - Shaarli plugin that enables user-defined callback URL, i.e. webhooks, for specific Shaarli events (link saving, deletion...)
 
 
-### Third-party themes
+### Themes
 
-See [Theming](dev/Theming.md) for a list of community-contributed themes, and an installation guide.
+- [AkibaTech/Shaarli Superhero Theme](https://github.com/MarceauKa/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
+- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
+- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
+- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
+- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
+- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
+- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site
+- [xfnw/shaarli-default-dark](https://github.com/xfnw/shaarli-default-dark) - The default theme but nice and dark for your eyeballs
+- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli (custom CSS)
 
 
 ### Integration with other platforms
 
-- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
+- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](https://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
 - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli Shaares on the sidebar
 - [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
-- [Shaarli app for Cloudron](https://git.cloudron.io/cloudron/shaarli-app) - [![](https://img.shields.io/badge/Cloudron-03A9F4?logo=Buffer)](https://cloudron.io/button.html?app=com.github.shaarli) Effortlessly run Shaarli with the help of [Cloudron](https://cloudron.io/) 
+- [Shaarli app for Cloudron](https://www.cloudron.io/button.html?app=com.github.shaarli) - [![](https://img.shields.io/badge/Cloudron-03A9F4?logo=Buffer)](https://www.cloudron.io/button.html?app=com.github.shaarli) Effortlessly run Shaarli with the help of [Cloudron](https://www.cloudron.io/)
 - [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - [![](https://img.shields.io/badge/YunoHost-black?logo=Buffer)](https://install-app.yunohost.org/?app=shaarli) Shaarli is available as a [Yunohost](https://yunohost.org) app
-- [shaarli_poster](https://github.com/getpelican/pelican-plugins/tree/master/shaarli_poster) - [pelican](https://blog.getpelican.com) static blog generator plugin to auto-post articles on a Shaarli instance
+- [shaarli_poster](https://github.com/getpelican/pelican-plugins/tree/master/shaarli_poster) - [pelican](https://getpelican.com) static blog generator plugin to auto-post articles on a Shaarli instance
 - [shaarli .deb package](https://packages.debian.org/search?keywords=shaarli) - for [Debian](https://www.debian.org/) and [Freedombox](https://www.freedombox.org/)
 
 
 ### Mobile apps
 
-- [ShaarliOS](https://github.com/mro/ShaarliOS) - [![](https://img.shields.io/badge/App%20Store-black?logo=apple)](https://itunes.apple.com/app/ShaarliOS/id1027441388) Apple iOS share extension.
+- [ShaarliOS](https://github.com/mro/ShaarliOS) - [![](https://img.shields.io/badge/App%20Store-black?logo=apple)](https://apps.apple.com/app/shaarlios/id1027441388) Apple iOS share extension.
 - [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=com.dimtion.shaarlier) Android application to simply add Shaares directly into your Shaarli via Sharing. Free software.
 - [Stakali for Android](https://stakali.toneiv.eu) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=eu.toneiv.stakali) Stakali is a personal bookmark manager which synchronizes with Shaarli. Support offline work without instance, sync, browsing within app. Free use of up to 20 results.
-- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider.
+- [Shaarli for Android](https://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider.
 
 
 ### Desktop apps
@@ -63,10 +71,10 @@ See [Theming](dev/Theming.md) for a list of community-contributed themes, and an
 
 ### Browser extensions
 
-- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [![](https://img.shields.io/badge/Firefox%20Add--ons-414141?logo=Firefox)](https://addons.mozilla.org/firefox/addon/shaarli/) toolbar button to share your current tab with Shaarli. 
-- [Shaarli Chrome Extension](https://github.com/octplane/Shiny-Shaarli) - toolbar button to share your current tab with Shaarli. [Removed](https://chrome.google.com/webstore/detail/shiny-shaarli/hajdfkmbdmadjmmpkkbbcnllepomekin) from Chrome web store.
+- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [![](https://img.shields.io/badge/Firefox%20Add--ons-414141?logo=Firefox)](https://addons.mozilla.org/en-US/firefox/addon/shaarli/) toolbar button to share your current tab with Shaarli.
 - [Add to Shaarli](https://github.com/burgyl/AddToShaarli) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/add-to-shaarli/jhfblapoehcfajokolimghdfmeeakbee) lets you add the current tab or a note to your Shaarli instance.
 - [WebLinks Ext](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) Save, edit and use your Shaarli. Support work offline, sync, trash, etc. Free software.
+- [Shaarli Chrome Extension](https://github.com/octplane/Shiny-Shaarli) - toolbar button to share your current tab with Shaarli. (Removed from Chrome web store).
 
 
 ### Server apps
@@ -78,25 +86,24 @@ See [Theming](dev/Theming.md) for a list of community-contributed themes, and an
 - [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
 - [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
 - [Self dead link](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
-- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
+- [Bookmark Archiver](https://github.com/ArchiveBox/ArchiveBox) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
 
 
 ## Alternatives to Shaarli
 
-See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing).
+See [awesome-selfhosted: bookmarks & link sharing](https://awesome-selfhosted.net/tags/bookmarks-and-link-sharing.html).
 
 
 ## Community
 
-- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
+- [Liens en vrac de sebsauvage](https://sebsauvage.net/links/) - the original Shaarli
 - [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
 - [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
 - [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
-- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
-- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
-- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
-- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
-- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
+- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](https://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
+- [Original ideas/fixme/TODO page](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
+- [Original discussion page](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
+- [Original revisions history](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
 
 
 ### Articles and social media discussions
@@ -111,4 +118,4 @@ See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/a
 It also appears in the following recommendation lists:
 - [AlternativeTo](https://alternativeto.net/software/shaarli/)
 - [FramaLibre](https://framalibre.org/content/shaarli)
-- [Project Awesome: Selfhosted Bookmarks and Link Sharing](https://project-awesome.org/Kickball/awesome-selfhosted)
+- [Awesome-Selfhosted - Bookmarks and Link Sharing](https://awesome-selfhosted.net/tags/bookmarks-and-link-sharing.html)