Generating Documentation with Sphinx

TLDR: Baqpaq’s documentation is now available online

I came across Sphinx a few months ago and found it very easy to use. Sphinx is a documentation generator – a tool that takes a bunch of text files formatted with Markdown (.md) or ReStructuredText (.rst), and outputs HTML files that are ready for publishing to a website.

Sphinx can be installed with the command:

pip install sphinx myst-parser sphinx-rtd-theme

The package myst-parser is required if you wish to use Markdown formatting in addition to ReStructuredText. MyST is a flavor of Markdown meant for technical documentation and publishing. It has all the features that you would normally expect in markdown ( CommonMark spec ) and provides additional features on top of it ( MyST Syntax Guide ).

The package sphinx-rtd-theme provides the theme created by the website ReadTheDocs.io

To start a new project, create a new folder, and run sphinx-quickstart

cd /path/to/project
mkdir docs
cd docs
sphinx-quickstart

The quickstart command will ask you a series of questions. Answer with Y or choose the default option. It will create the basic folder structure, which you can then customize according to your requirements.

Create text files for the information that you want to publish. Add the file names to index.rst

Edit the file conf.py if you wish to change the theme:

html_theme = "sphinx_rtd_theme"

When you are ready to publish, run:

make html

HTML files are generated in the directory _build/html. You can copy the contents of this folder directly to your web server. This is a statically-built website without external dependencies.

Baqpaq 21.10

Baqpaq 21.10 is available with some minor changes.

• Documentation was updated and moved online. Click the Help button in the toolbar to open the web link.
• Package size is reduced from 1.8 MB to 330 KB after removing the PDF document
• Fix: Don’t create empty snapshots if the folders to include are missing
• Fix: Free disk space is not shown in statusbar for virtual (fuse) file systems
• Fix: Enable “Tools” in toolbar if profile fails to load
• UI: Rename references to action “Restore” to “Extract” in the GUI
• UI: Schedule: Use 3-letter abbreviation for weekday names
• Minor UI changes