linuxmuster.net documentation

The full documentation of linuxmuster.net.

Installation

Clone the repository "main" using git

~$ git clone https://github.com/linuxmuster-docs/main.git  # if you have no ssh-key within github
~$ git clone git@github.com:linuxmuster-docs/main.git # if you have a ssh-key within github

Install sphinx, e.g. under Ubuntu 20.04, do

~$  sudo apt install git python3-sphinx texlive texlive-latex-extra texlive-lang-german

Make a local copy of your documentation using

~$ cd main
~/main$ make clean
~/main$ make html

Later, if you work again on the repository, update it with

~/main$ git pull

Contribute to the documentation

Fork the repository "main" within the github-webinterface

• Clone your fork

  ~$ git clone https://github.com/mein-github-konto/main.git docs
  ~$ cd docs
  ~/docs$ make html

• Make changes in your fork

• Commit your changes to your fork

  ~/docs$ git commit -a -m"bugfix for bug in ticket #314 ..."

• Push your changes to your fork on github

  ~/docs$ git push

• Create a new pull-request on github

• If you are done and the pull-request was merged, you can delete your fork and create a new one.

Update your fork

Instead of deleting and creating a new fork you can bring your own fork up-to-date the following way:

• Any changes you made you have to stash away for a while:

  ~/docs$ git stash

• Add a remote tracking branch once:

  ~/docs$ git remote add upstream https://github.com/linuxmuster-docs/main.git

• Fetch and merge the remote master

  ~/docs$ git fetch upstream
  ~/docs$ git merge upstream/master

• (If the merge does not end in an fast-forward result, you better delete and refork.) Push your changes into your fork.

  ~/docs$ git push

• Now you can get your stashed away changes:

  ~/docs$ git stash pop

Guidelines for documentation

The structure guide and style guide provide information on the design of our documentation. See our Guidelines https://docs.linuxmuster.net/de/latest/appendix/contribute/docs/guidelines.html

Translation

We use Transifex to translate the documentation. Get started there!

Build documentation in English

First you have to install sphinx-intl and the transifex-client.

$ pip install sphinx-intl
$ pip install transifex-client

Make sure that sphinx-intl and transifex-client are in your PATH!

Then run to following commands (inside the document root):

$ make gettext
$ tx init
$ sphinx-intl update -p build/locale -l en
$ sphinx-intl update-txconfig-resources --pot-dir build/locale --transifex-project-name official-documentation
$ tx pull -l en
$ make -e SPHINXOPTS="-D language='en'" html

Read the Internationalization chapter in the offical sphinx documentation for a more detailed description.

Further reading

See the documentation on linuxmuster.net.