Help building documentation

[qinohe]

Hey all,

A while ago a read about how difficult some people find it to write docs in RST format and how easy it would be to use traditional wiki format. RST is a very simple markup language no more difficult then wiki markup, you can learn it and write a short page in an hour or so.

What I would like to show here is how to write your RST page in a clean environment similar to chroot on a linux system using systemd-nspawn and Debian as guest.
Of course you need Linux using systemd as init system...

Sorry to all non Linux users, but there are a lot of documents already to achieve the same.

I will not go into using git and creating a clone of the docs on your own GitHub page.


The fun part:

=====================================================================
edit: first look at the commands used in post #3, as fabian pointed out in post #2, Thanks  ;)
=====================================================================

Okay first you need some space to setup a container(systemd-nspawn). The size of a fully setup system would be less than 1G so a few Gigs free space would be more than enough.

Create a directory and name it, something like 'opndocs'.

Become root and be sure you cd to '../opndocs'

Time to setup the system, we use Debian stretch(old-stable)
You can try buster but it wont work on my Arch Linux system, yet.

Code Select Expand

debootstrap --include=systemd-container --components=main,universe stretch opndocs https://deb.debian.org/debian/
This mostly takes a few minutes depending on your connection/system

Next we must set a password:

Code Select Expand

systemd-nspawn -D opndocs
passwd
logout

Now it's time to start the container and login

Code Select Expand

systemd-nspawn -b -D opndocs

Install a few programs in the container:

Code Select Expand

apt-get install vim git python-pip

Time to clone the docs, don't use 'mine', create your own clone...

Code Select Expand

git clone https://github.com/qinohe/docs  # example

Install Spinx, contrib packages & OPNsense default theme with pip:

Code Select Expand

cd docs
pip install -r requirements.txt

Create a page.rst page there are examples enough in the directory.
page.rst is an example name it logic. If you write a page about ssh security, name it something like ssh-security.rst.

When you're done creating a page you need to create the wiki. There is a makefile in 'docs' dir:

Code Select Expand

make html

Upload the result to your system/web-server test them and see if you want to change anything
The resulting files are in:

Code Select Expand

docs/build/html

If you need to edit your created file cd to docs:

Code Select Expand

make clean

Make you're changes and 'make html', upload & 'make clean' etc.

When you're ready upload the docs back to your GitHub and make a pull request to OPNsense-docs

Note: if you don't have a GitHub page and don't want to setup one, clone the docs directly from OPNsense:

Code Select Expand

git clone https://github.com/opnsense/docs
Make your page and send it to the devs directly. They will accept it, but please take the effort to setup your own...

That's all, hope this helps users who want to but didn't know how to ;)

Greetings mark

[fabian]

I would recommend to do it differently. If you have python installed, you can use virtual env to avoid conflicts. It is in most time also better to run the same distribution on the container and the container. Differences may cause errors especially when the host has features the container does not expect like SELinux.

Also as a short note: You can open the files directly. There is no Webserver required.

[qinohe]

I would recommend to do it differently. If you have python installed, you can use virtual env to avoid conflicts. It is in most time also better to run the same distribution on the container and the container. Differences may cause errors especially when the host has features the container does not expect like SELinux.

Hi fabian, thanks for the answer. Must say I never had real issues using systemd-nspawn but I see what mean.
I'm not a coder so I didn't know about 'virtualenv' but will read the wiki/man and rewrite the above for that.

Also as a short note: You can open the files directly. There is no Webserver required.

I know, that's why I said 'system / webserver', both will do, I mostly uploaded the files to my server since it's already there ;)

Greetings, mark

[qinohe]

Have tried to use virtualenv on Arch like so:

Code Select Expand

python -m venv venv
source venv/bin/activate
git clone https://github.com/qinohe/docs
pip install --upgrade pip
pip install -r requirements.txt
make html

I think I have done it the way it supposed to be done.
I'm presented with an error I have already filed a bug report for a long time ago, but maybe the dev don't think it's urgent I don't know :(
So for now until this is fixed I'm sticking to systemd-nspawn which has done a good job so far.
The bug-report:  https://github.com/blockdiag/sphinxcontrib-nwdiag/issues/2

edit: The bug in sphinxcontrib-nwdiag has been solved and so the commands in this post work as expected again.
Depending on your environment you should probably use python-virtualenv in the first place and use systemd-nspawn only as a last resort.

Greetings, mark