From 042bf60776f1c698a3c78324d892123d9d1640ef Mon Sep 17 00:00:00 2001 From: Fabian Senf Date: Thu, 22 Jun 2023 15:33:55 +0200 Subject: [PATCH 1/3] undo mock of numpy import when docs rendering is done --- doc/conf.py | 2 +- doc/requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 0f5e48ea..e897fd7e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -43,7 +43,7 @@ def setup(app): # This should include all modules used in tobac. These are dummy imports, # but should include both required and optional dependencies. autodoc_mock_imports = [ - "numpy", +# "numpy", "scipy", "scikit-image", "pandas", diff --git a/doc/requirements.txt b/doc/requirements.txt index 82f69f75..6ba789a0 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,2 +1,3 @@ ipykernel nbsphinx +numpy From 40b104ad0770726c1d01c1406ab35955c08ab4bf Mon Sep 17 00:00:00 2001 From: Fabian Senf Date: Thu, 22 Jun 2023 16:05:38 +0200 Subject: [PATCH 2/3] added also a short doc how to run sphinx rendering locally --- doc/Testing-Sphinx-based-Rendering.md | 112 ++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 doc/Testing-Sphinx-based-Rendering.md 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 + ``` + From 054588d382e4887709eedf601c47123b45ea5e12 Mon Sep 17 00:00:00 2001 From: Fabian Senf Date: Fri, 7 Jul 2023 15:32:46 +0200 Subject: [PATCH 3/3] removed sphinx rendering description from branch --- doc/Testing-Sphinx-based-Rendering.md | 112 -------------------------- 1 file changed, 112 deletions(-) delete mode 100644 doc/Testing-Sphinx-based-Rendering.md diff --git a/doc/Testing-Sphinx-based-Rendering.md b/doc/Testing-Sphinx-based-Rendering.md deleted file mode 100644 index 68d0bfae..00000000 --- a/doc/Testing-Sphinx-based-Rendering.md +++ /dev/null @@ -1,112 +0,0 @@ - -# 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 - ``` -