diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 119 |
1 files changed, 81 insertions, 38 deletions
@@ -1,74 +1,117 @@ -This is a playground for a new VyOS documentation starting for VyOS 1.2 (Crux) -release. +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 + +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 -## Native +[](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) +* ... + +### sphinx +Debian requires some extra steps for +installing `sphinx`, `sphinx-autobuild` and `sphinx-rtd-theme` packages: + +First ensure that Python 2 & Python 3 are installed and Python 3 is the default: +```bash +python --version +``` + +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 install the sphinx group of packages: +```bash +sudo apt-get install python3-sphinx +``` -To build the manual run the following commands inside the `docs` folder: +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: -* `make html` for a HTML manual -* `make latexpdf` for a LaTeX rendered PDF +```bash +python --version +``` -Required Debian Packages: -* `python-sphinx` -* `python-sphinx-rtd-theme` -* `latexmk` -* `texlive-latex-recommended` -* `texlive-fonts-recommended` -* `texlive-latex-extra` +Then run: -### sphinx-autobuild -Required extra setup procedure on Debian: ```bash -sudo apt-get install python-pip -sudo pip install sphinx-autobuild +sudo pip install sphinx-rtd-theme ``` -To build and run a webeserver, inside the `docs` folder: -* `make livehtml` and browse to http://localhost:8000 +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 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 prebuilt +from Dockerhub. If you want to build it for yourself, use the following command. + ```bash -$ docker build -t vyos-docu docker +$ docker build -t vyos/vyos-documentation docker ``` -### Build +### Building documentation -Linux -```bash -$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos-docu 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-docu make livehtml -``` +If the `vyos/vyos-documentation` container could not be found locally it will be +automatically fetched from Dockerhub. -Windows -```powershell -docker run --rm -it -v "$(pwd):/vyos" -w /vyos/docs vyos-docu make html +```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 vyos-docu make livehtml +$ 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 Task: [T1731](https://phabricator.vyos.net/T1731) +Discuss in this Phabricator task: [T1731](https://phabricator.vyos.net/T1731) -to test all files: +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-docu vale . +$ 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) -e GOSU_GID=$(id -g) vyos-docu vale clustering.rst +$ 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 ``` |