Renovate whole setup

* Move source files to `./source/`. * Build to `./build/`. * Use `Makefile` template from newer sphinx version and expand it only as necessary. * Produce an index file for the intermediate directories of the expected URL (which is unchanged because it's published by the `help` plugin in so many places). * Use more modern theme ("pyramid") to make the text even readable again. This change does *not* deal with the outdated content or the lack of versioning scheme for it.
roundcube · Oct 21, 2024 · fc2e295 · fc2e295
1 parent cd2d852
commit fc2e295
Show file tree

Hide file tree

Showing 44 changed files with 151 additions and 768 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+source/locale/
+pages/
+build/
diff --git a/Makefile b/Makefile
@@ -1,42 +1,60 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SOURCE        = en_US
-VERSION       = 1.1
-LANGUAGE      = en
-INTL_LOCALES  = -l de -l fr -l sk
-# use tags to include documentation for specific plugins
-TAGS          = -t archive -t acl -t zipdownload -t v1.1
-SPHINXOPTS    = -c . -D language='$(LANGUAGE)' -D version='$(VERSION)' -D release='$(VERSION)'
-SPHINXBUILD   = sphinx-build
-SPHINXINTL    = sphinx-intl
-BUILDDIR      = _build
-
-ALLSPHINXOPTS = $(SPHINXOPTS) $(TAGS) -d $(BUILDDIR)/doctrees/$(SOURCE)
-I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE) $(TAGS)
-
-all: html
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS   ?=
+SPHINXBUILD  ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Use the two-character language code here, else the .po files are not found.
+LANGUAGE     ?= en
+VERSION      ?= 1.1
+TAGS         ?= -t archive -t acl -t zipdownload
+
+
+.PHONY: help Makefile clean push-to-transifex pull-from-transifex en de fr sk pages
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	rm -rf $(BUILDDIR)/html
-	mkdir -p $(BUILDDIR)/locale/_plugins
-
-html: conf.py _static/default.css
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SOURCE) $(BUILDDIR)/html/doc/help/$(VERSION)/$(SOURCE)
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/doc/help/$(VERSION)/$(SOURCE)."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	$(SPHINXINTL) update -p $(BUILDDIR)/locale -d locale $(INTL_LOCALES)
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-update-txconfig-resources:
-	@echo "Removing _plugins locale files..."
-	rm -rf locale/*/LC_MESSAGES/_plugins/*
-	rm -rf $(BUILDDIR)/locale/_plugins/*
-	$(SPHINXINTL) update-txconfig-resources --transifex-project-name roundcube-webmail-help -p $(BUILDDIR)/locale -d locale
-	@echo
-	@echo "Transifex resources have been updated."
+	rm -rvf build pages source/locale
+
+push-to-transifex: clean gettext
+	sphinx-intl update-txconfig-resources --transifex-organization-name roundcubemail --transifex-project-name roundcube-webmail-help
+	tx push -s
+
+pull-from-transifex: gettext
+	tx pull -l $(LANGUAGE)
+
+pages-mkdir:
+	mkdir -p pages/doc/help/$(VERSION)
+
+en: pages-mkdir
+	make html
+	mv -v build/html pages/doc/help/$(VERSION)/en_US
+	# Copy the generic index to all intermediate directories to provide links to the actual docs.
+	mv -v pages/doc/help/$(VERSION)/en_US/generic-index.html pages/index.html
+	sed -i -e 's#<head>#<head>\n<base href="/doc/help/1.1/en_US/">#' pages/index.html
+	cp -v pages/index.html pages/doc/
+	cp -v pages/index.html pages/doc/help/
+	cp -v pages/index.html pages/doc/help/$(VERSION)/
+
+de: pages-mkdir
+	make LANGUAGE=de pull-from-transifex html
+	mv -v build/html pages/doc/help/$(VERSION)/de_DE
+
+fr: pages-mkdir
+	make LANGUAGE=fr pull-from-transifex html
+	mv -v build/html pages/doc/help/$(VERSION)/fr_FR
+
+sk: pages-mkdir
+	make LANGUAGE=sk pull-from-transifex html
+	mv -v build/html pages/doc/help/$(VERSION)/sk_SK
+
+pages: clean en de fr sk
+
+# 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)" -t v$(VERSION) $(TAGS) -D version=$(VERSION) -D language=$(LANGUAGE) $(SPHINXOPTS) $(O)
diff --git a/README.md b/README.md
@@ -15,14 +15,22 @@ First of all you need Python and [Sphinx][sphinx] installed. Grab the latest ver
 
 	sudo easy_install -U Sphinx
 
+Alteratively you can use a container image. Have a look at `install-deps-in-sphinx-container.sh`.
+
 This repo already contains the Sphinx project configuration and can be generated
 right away with the following command:
 
 	cd <this-repo-checkout-dir>
-	make
+	make html
 
 The above example generates the English (US) online help files with English localization
-for the navigation into the `_build/html/1.0/en_US` output directory.
+for the navigation into the `build/html/en_US` output directory.
+
+To generate the pages for all available languages and produce the document tree that is served on <https://docs.roundcube.net>, run:
+
+	make pages
+
+This builds the document tree in the `pages` directory.
 
 
 Integrating Help for Plugins
@@ -64,17 +72,23 @@ Generating Translated Files
 	tx pull -f -l fr
 	```
 
-2. Compile `.mo` files:
-
-	```
-	sphinx-intl build
-	```
-
 3. Run Sphinx to build the localized docs by using the LANGUAGE parameter:
 
 	```
 	make LANGUAGE=fr html
 	```
+   (Note: do not specify a 5-character `locale` here, it won't work.)
+
+
+Adding languages
+----------------
+
+To add a language to the list of generated pages, follow these steps:
+
+1. Add a section to the `Makefile`.
+1. Add the language to the `pages` target in the `Makefile`.
+2. Add a link to `source/_static/generic-index.html`
+
 
 Skins Support
 -------------

diff --git a/_ext/__init__.py b/_ext/__init__.py