Repository for building the documentation pages for the Fortran package manager (fpm).
git clone https://github.com/fortran-lang/fpm-docs
cd fpm-docs
The documentation pages are created using sphinx. You first need to install the required dependencies using conda or pip. This project uses
- sphinx-build for building the pages
- sphinx-intl for translations
- ablog for the news section and posts
- sphinx-book-theme for the page theme
- myst-parser for markdown support
- sphinx-design for the bootstrap building blocks
- sphinx-copybutton to allow copying of code-blocks
- sphinx-jinja to use templating for the registry
conda env create -n sphinx -f environment.yaml
conda activate sphinx
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -r requirements.txt
Build the documentation by invoking
make html
The website will be built in _build/html and can be previewed by opening the page with a browser (e.g. firefox, chromium or similar):
firefox file://$PWD/_build/html/index.html
By default all languages will be built. To limit the build to a single language subtree, i.e. English, use
make html LANGUAGES=en
Translations can be contributed via weblate.
The documentation uses the
sphinx-intl
utility to generate websites for multiple languages.
It generates *.po files,
which contain the original sentences and a placeholder for translations.
To update translations run
make gettext
if you only want to update a single translation add LANGUAGES=de to the command.
This command will generate the message catalog (*.pot) and update the *.po files in the locale directory of the respective translations.
Then edit the *.po files,
e.g. locale/de/LC_MESSAGES/index.po.
In the *.po files are paragraphs like
#: ../../pages/index.md:16
msgid "Package manager and build system for Fortran"
msgstr ""The first line describes the file and line where to find the original text.
The second line is the original text. Don't edit this line, edit the original document instead.
The third line is meant for the translation.
To continue a long string in another line,
simply close the string in the current line with "
and open another one in the line underneath. E.g.
msgstr "This is "
"one string"
don't forget a space between 'is' and 'one'
After adding or updating translations build the documentation as described above.
You can build the Preview of the fpm-docs website by opening a pull request
and commenting #preview on the pull request. Similarly, you can force the
deletion of the preview by commenting #delete-preview.