diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 57 |
1 files changed, 39 insertions, 18 deletions
@@ -1,17 +1,38 @@ -Starting with VyOS 1.2 (`crux`) documentation will be migrated from the old wiki -to ReadTheDocs. Documentation can be accessed via the following URL: +Starting with VyOS 1.2 (`crux`) our documentation is being migrated from the old wiki +to ReadTheDocs. Documentation can be accessed via the following URL: https://docs.vyos.io -* https://docs.vyos.io +Our old WiKi can still be accessed from the +[Wayback Machine](https://web.archive.org/web/20200225171529/https://wiki.vyos.net/wiki/Main_Page) # Build [](https://docs.vyos.io/en/latest/?badge=latest) +# Versions + +Our version follows the very same branching scheme as the VyOS source modules +itself. We maintain one documentation branch per VyOS release. The default +branch that contains the most recent VyOS documentation is called `master` +and matches the latest VyOS release which is 1.4 at the time. + +All new documentation enhancements go to the `master` branch. If those changes +are beneficial for previous VyOS documentation versions they will be +cherry-picked to the appropriate branch(es). + +Post-1.2.0 branches are named after constellations sorted by area from smallest to +largest. There are 88 of them, here's the +[complete list](https://en.wikipedia.org/wiki/IAU_designated_constellations_by_area). + +* 1.2.x: `crux` (Southern Cross) +* 1.3.x: `equuleus` (Little Horse) +* 1.4.x: `sagitta` (Arrow) +* ... + ## Native -To build the manual run the following commands inside the `docs` folder: +To build the manual, run the following commands inside the `docs` folder: -* `make html` for a HTML manual +* `make html` for an HTML manual * `make latexpdf` for a LaTeX rendered PDF Required Debian Packages: @@ -22,28 +43,28 @@ Required Debian Packages: * `sphinx` ### sphinx -Debian, requires some extra steps for +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: +First ensure that Python 2 & Python 3 are installed and Python 3 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: +Alternatively, to make Python the default, revise the following line to +point at 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: +Then install the 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: +Although almost everything uses Python 3, in order to install this specific +package, make sure that pip points at the Python 2 version of the package manager: ```bash python --version @@ -56,29 +77,29 @@ sudo pip install sphinx-rtd-theme ``` -Do the following to build the html and start a webeserver: +Do the following to build the HTML and start a webserver: * 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 +Note: The changes you save to the sources are represented in the live HTML output automatically (and almost instantly) without the need to rebuild or refresh manually. ## Docker -Using our [Dockerfile](docker/Dockerfile) you create your own Docker container +Using our [Dockerfile](docker/Dockerfile) you can 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 +You can either build the container on your own or directly fetch it prebuilt from Dockerhub. If you want to build it for yourself, use the following command. ```bash $ docker build -t vyos/vyos-documentation docker ``` -### Build documentation +### Building documentation If the `vyos/vyos-documentation` container could not be found locally it will be automatically fetched from Dockerhub. @@ -103,7 +124,7 @@ $ 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` +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) \ |