Root Pages is a collection of quick and easy-to-reference tutorials, examples, and guides primarily for Linux and other UNIX-like systems. The main goal of this project is to provide a more general purpose alternative to the "info" documents for System Administrators, Engineers, and Architects. Each page is a full guide to each topic. This makes it easy to navigate and search for content.
All Root Pages are written in the reStructuredText (RST) markup language. Sphinx is used for building the documentation into ePub, HTML, PDF, and other common document formats.
- Stable updates: https://rootpages.lukeshort.cloud/
- Latest development updates: https://rootpages.lukeshort.cloud/latest/
All commits to Root Pages are automatically tested via a GitHub Actions workflow. The latest successful build of the "main" branch is pushed to a Kubernetes cluster. Tags are published and a "stable" branch is updated quarterly.
Sphinx is a Python package that is required to compile Root Pages into different document formats. It is provided by most operating systems' package manager. The official installation guide can be found here.
Arch Linux:
$ sudo pacman -S python-sphinx python-sphinx_rtd_theme
Debian:
$ sudo apt-get install python3-sphinx python3-sphinx-rtd-theme
Fedora:
$ sudo dnf install python3-sphinx python3-sphinx_rtd_theme
macOS:
$ brew install python3
$ pip3 install -U sphinx sphinx-rtd-theme
$ export PYTHON_VERSION="3.9"
$ export PATH="$PATH:${HOME}/Library/Python/${PTYHON_VERSION}/bin/"
openSUSE:
$ sudo zypper install python3-Sphinx python3-sphinx_rtd_theme
Some operating systems will install the sphinx-build binary with a different suffix to indicate that it is using Python 3. For ease of use, consider symlinking that to be sphinx-build.
$ sudo ln -s /usr/bin/sphinx-build-3* /usr/local/bin/sphinx-build
Sphinx will save newly generated documents into the "build/" directory by default.
ePub:
$ make epub
HTML:
$ make html
HTML via the Docker Engine (all operating systems):
$ docker run --rm -v ${PWD}:/docs sphinxdoc/sphinx /bin/sh -c 'pip install sphinx_rtd_theme && make html'
PDF:
$ make latexpdf
Text:
$ make text
The "sphinx-build" command is more flexible by being able to add additional command-line arguments to it. It also does not require the "make" system package to be able to process and execute the Makefile.
Specify the format that the reStructuredText should be transformed and output into, and both the source and build directories.
$ sphinx-build -b <OUTPUT_FORMAT> src/ build/
A custom dictionary is provided to do spell checking. However, the hunspell command does not reliably use every word in the dictionary so manual review is still required.
$ hunspell -l -d en_US -p ./hunspell_dictionary_root_pages.txt src/*/*.rst
Root Pages can also be translated into a different language.
- Convert the documents' text into the gettext
*.potformat.
$ make gettext
- Compile the
*.potfiles into the*.poformat.
$ sphinx-intl update -p build/gettext -l <LOCALE>
- Translate the
*.pofiles. - Build the translated documentations.
$ make -e SPHINXOPTS="-D language='<LOCALE>'" html
Root Pages is a rolling release. As new information is committed, it is shortly pushed into master after a quick review for technical writing standards and correct citation usage.
All updates should be added to the reStructuredText files in the "src/" directory of this project. These documents are currently in English and translations are always welcome!
A few quick notes about technical documentation:
- Everything should be written in the third-person narrative.
- Sentences should be easy-to-read and quick to the point.
- Chicago style citation to sources are required for all pages except for linux_commands.
- Linux Commands are assumed to reference the official manual and information pages provided by the software.
- If assistance is required with the syntax of new citations, check out Citation Machine.
Recommended text editors:
- Graphical User Interface (GUI):
- Atom with these optional plugins:
- sphinx-preview. Hint: Open the rendered HTML preview page by pressing
CONTROL+ALT+otogether.- This requires the "brower-plus" plugin and that the current user have access to manage docker containers.
- The
dockercontainer platform should be installed. The user runningatomalso needs privileges to manage docker containers.
- rst-snippets. Hint: Create a generic Markdown or RST table outline and then press
CONTROL+ALT+ttogether and thenENTERto automatically reformat it correctly.
- sphinx-preview. Hint: Open the rendered HTML preview page by pressing
- Atom with these optional plugins:
- Command-Line Interface (CLI):
- Vim with this plugin:
RST header characters to use:
=====-----~~~~~^^^^^'''''&&&&&
Any arguments or options that are required for a command or configuration are marked in bold.
There are a lot of issues open on GitHub that have the label "new content." These issues indicate that a new subject matter should be added into an existing document. These normally have at least one link to a source article that can be referenced or at least used as a starting point for further research.
Every three months, Root Pages is tagged as a milestone release. The four releases in a year are: YYYY.01.01, YYYY.04.01, YYYY.07.01, and YYYY.10.01. Quarterly updates minimize breakage to bookmarks and links compared to a rolling release model. Formatting, grammar, and spelling errors should be checked and corrected before each tagged release.
The copyright year in src/conf.py needs to be updated.
Root Pages, and all of it's content, is provided under the GNU Free Documentation License (GFDL) v1.3. Additional disclaimers related to warranty and liability from the GPLv3 license are also applied to this project.
Files:
- LICENSE
- DISCLAIMER
Root Pages strives to provide proper citation to the original authors to give credit where due. If there are any reports of plagiarism, please open a new GitHub issue for it to get addressed.