blob: 5594baae4c4243c225e801fb69c4db286c4a54ad (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
Starting with VyOS 1.2 (`crux`) documentation will be migrated from the old wiki
to ReadTheDocs. Documentation can be accessed via the following URLs:
* https://docs.vyos.io
* https://vyos.readthedocs.org
# Build
[](https://docs.vyos.io/en/latest/?badge=latest)
## Native
To build the manual run the following commands inside the `docs` folder:
* `make html` for a HTML manual
* `make latexpdf` for a LaTeX rendered PDF
Required Debian Packages:
* `latexmk`
* `texlive-latex-recommended`
* `texlive-fonts-recommended`
* `texlive-latex-extra`
* `sphinx`
### sphinx
Debian, requires some extra steps for
installing `sphinx`, `sphinx-autobuild` and `sphinx-rtd-theme` packages:
First ensure that phython2 & phython3 are installed and phython3 is the default:
```bash
python --version
```
Alternatively, to make python3 the default, revise the following line to
point to the relevant 3.x version of the binary on your system:
```bash
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 0
```
Then follow these steps to install sphinx group of packages:
```bash
sudo apt-get install python3-sphinx
```
Although mostly everything uses phython3, But to install this specific
package, make sure that pip points to the python2 version of the package manager:
```bash
python --version
```
Then run:
```bash
sudo pip install sphinx-rtd-theme
```
Do the following to build the html and start a webeserver:
* Run `make livehtml` inside the `docs` folder
Then, to view the live output:
* Browse to http://localhost:8000
Note: The changes you save to the sources are represented in the live HTML outout
automatically (and almost instantly) without the need to rebuild or refresh manually.
## Docker
Using our [Dockerfile](docker/Dockerfile) you create your own Docker container
that is used to build a VyOS documentation.
## Setup
You can either build the container on your own or directly fetch it prebuild
from Dockerhub. If you want to build it for yourself, use the following command.
```bash
$ docker build -t vyos/vyos-documentation docker
```
### Build documentation
If the `vyos/vyos-documentation` container could not be found locally it will be
automatically fetched from Dockerhub.
```bash
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
-e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html
# sphinx autobuild
$ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e \
GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml
```
### Test the docs
Discuss in this Phabricator task: [T1731](https://phabricator.vyos.net/T1731)
To test all files run:
```bash
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
-e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale .
```
to test a specific file e.g. `clustering.rst`
```bash
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) \
-e GOSU_GID=$(id -g) vyos/vyos-documentation vale clustering.rst
```
|
