diff --git a/doc/Testing-Sphinx-based-Rendering.md b/doc/Testing-Sphinx-based-Rendering.md new file mode 100644 index 00000000..68d0bfae --- /dev/null +++ b/doc/Testing-Sphinx-based-Rendering.md @@ -0,0 +1,112 @@ + +# How to Check if Sphinx-based Rendering of `tobac` is Working? + + +The workflow has been tested in a linux system. We aim to build a static website out of the documentation material present in `tobac`. + + +## 1. Preparing the Local Environment + +* **choose a separate place for your testing** + + I will use the temporary directory `/tmp/website-testing` which I need to create. You can use a dedicated place of your choice ... + + ```bash + > mkdir /tmp/website-testing + > cd /tmp/website-testing + ``` + I will indicate my position now with the `/tmp/website-testing>` prompt. + +* **get the official repository** + + ```bash + /tmp/website-testing> git clone https://github.com/tobac-project/tobac + ``` + + You might like to test a certain remote branch `` then do: + + ```bash + git fetch --all + git checkout -t origin/ + ``` + +* **Python environment** + * create a python virtual env + ```bash + /tmp/website-testing> python -m venv .python3-venv + ``` + + * and install requirements + ```bash + # deactivation conda is only necessary if your loaded conda before ... + /tmp/website-testing> conda deactivate + + # activate the new env and upgrade `pip` + /tmp/website-testing> source .python3-venv/bin/activate + /tmp/website-testing> pip install --upgrade pip + + # now everything is installed into the local python env! + /tmp/website-testing> pip install -r tobac/doc/requirements.txt + + # and also install RTD scheme + /tmp/website-testing> pip install sphinx_rtd_theme + + ``` + `pip`-based installation takes a bit of time, but is much faster than `conda`. If the installation runs without problems, you are ready to build the website. + + +## 2. Building the Website + +Actually, only few steps are needed to build the website, i.e. + + +* **running sphinx for rendering** + + ```bash + /tmp/website-testing> cd tobac + + /tmp/website-testing/tobac> sphinx-build -b html doc doc/_build/html + ``` + + If no severe error appeared + + +* **view the HTML content** + + ```bash + /tmp/website-testing/tobac> firefox doc/_build/html/index.html + ``` + + +## 3. Parsing Your Local Changes + +Now, we connect to your locally hosted `tobac` repository and your development branch. + +* **connect to your local repo**: + Assume your repo is located at `/tmp/tobac-testing/tobac`, then add a new remote alias and fetch all content with + + ```bash + /tmp/website-testing/tobac> git remote add local-repo /tmp/tobac-testing/tobac + /tmp/website-testing/tobac> git fetch --all + ``` +* **check your development branch out**: + Now, assume the your development branch is called `my-devel`, then do + + ```bash + # to get a first overview on available branches + /tmp/website-testing/tobac> git branch --all + + # and then actually get your development branch + /tmp/website-testing/tobac> git checkout -b my-devel local-repo/my-devel + ``` + + You should see your developments, now ... + +* **build and view website again** + + ```bash + /tmp/website-testing/tobac> sphinx-build -M clean doc doc/_build + /tmp/website-testing/tobac> sphinx-build -b html doc doc/_build/html + /tmp/website-testing/tobac> firefox _build/html/index.html + ``` +