Add info about Python venv and tune CI (0.3.11)

Signed-off-by: Jorge Marques <[email protected]>

.github/workflows/build-doc.yml

@@ -7,10 +7,12 @@ on:
 
 jobs:
   on-success:
+    name: Deploy doc
     runs-on: ubuntu-latest
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     permissions:
       contents: write
+
     steps:
     - name: Set up Python
       uses: actions/setup-python@v4
@@ -36,25 +38,25 @@ jobs:
         email=$(git log -1 --pretty=format:'%ae')
         commit=$(git rev-parse --short HEAD)
 
-        mkdir /tmp/sphinx_doc
+        mkdir /tmp/doc
         rm -r docs/_build/html/_sources
-        cp -r docs/_build/html/* /tmp/sphinx_doc
+        cp -r docs/_build/html/* /tmp/doc
         git stash --all
-        git fetch origin
+        git fetch origin gh-pages
         git checkout -b gh-pages origin/gh-pages
         git rm -r . --quiet
-        cp -r /tmp/sphinx_doc/* .
+        cp -r /tmp/doc/* .
         touch .nojekyll
 
         git add . >> /dev/null
         git config --global user.name "$author"
         git config --global user.email "$email"
-        git commit -m "deploy: $commit"
+        git commit -m "deploy: $commit" --allow-empty
 
     - name: Push to gh-pages
       run: >-
         git push origin gh-pages:gh-pages
 
     - name: Clean-up
       run: >-
-        rm -r /tmp/sphinx_doc
+        rm -r /tmp/doc

README.md

@@ -32,6 +32,22 @@ repositories.
 [1] There is a [known bug](https://github.com/pypa/setuptools/issues/3269)
 with pip shipped with Ubuntu 22.04
 
+### Using a Python virtual environment
+
+Installing packages at user level through pip is not always recommended, instead,
+consider using a Python virtual environment (``python3-venv`` on ubuntu 22.04).
+To create and activate the environment, do before the previous instructions:
+```
+python3 -m venv ./venv
+source ./venv/bin/activate
+```
+Use ``deactivate`` to exit the virtual environment.
+
+For next builds, just activate the virtual environment:
+```
+source ./venv/bin/activate
+```
+
 ## Development install
 
 Development mode allows to edit the source code and apply the changes without

adi_doctools/__init__.py

@@ -6,7 +6,7 @@
 from .directive import setup as directive_setup
 from .role import setup as role_setup
 
-__version__ = "0.3.10"
+__version__ = "0.3.11"
 
 
 def get_navigation_tree(app, context, pagename):

docs/install.rst

@@ -30,6 +30,28 @@ Test it building this documentation:
 .. [#f1] There is a `known bug <https://github.com/pypa/setuptools/issues/3269>`_
    with pip shipped with Ubuntu 22.04.
 
+
+Using a Python virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Installing packages at user level through pip is not always recommended, instead,
+consider using a Python virtual environment (``python3-venv`` on ubuntu 22.04).
+
+To create and activate the environment, do before the previous instructions:
+
+.. code::
+
+   python3 -m venv ./venv
+   source ./venv/bin/activate
+
+Use ``deactivate`` to exit the virtual environment.
+
+For next builds, just activate the virtual environment:
+
+.. code::
+
+   source ./venv/bin/activate
+
 .. _development-install:
 
 Development install