Funkwhale’s documentation is written using reStructuredText and is built using Sphinx.
As reStructuredText is a writing standard, any text editor can be used to modify documents depending on preference. User-friendly programs such as Retext are good options for those just getting started with writing reStructuredText. Many other editors such as Vim, Emacs, VS Code, and Atom have addons which can help with syntax highlighting and live previewing.
Sphinx is used to generate a static site based on the
.rst files in the
docs directory. When writing
documents, it can be useful to build the site to see how your changes will look in production. To do this:
Install Sphinx using pip
pip install sphinx
Navigate to your local
Use the make file to build the site
Sphinx will generate the site in your
funkwhale/docs/_builddirectory unless otherwise stated
Once you have generated a local copy of the site, you can open it up by opening the index.html file in
If you are familiar with Docker and docker-compose,
you can also hack on the documentation via a single command:
docker-compose -f dev.yml up docs.
This will make the documentation available at http://0.0.0.0:8001, with live-reloading enabled, so any change made in the
.rst files will be reflected immediately in your browser.
In order to work on files on your computer, you will need to install git for your operating system. Git is used to push and pull files to and from the Funkwhale repository and track changes made to documents/code alike.
If you are only making minor changes to a document or don’t wish to install anything, you can use Gitlab’s built-in IDE. Once you have made an account and created a pull request, you can click on the “Open in Web IDE” button to open up a fully-fledged editor in your web browser.