0

I am currently working on a cython project.

After following some tutorials, I was able to build in place cython, then use sphinx build with the line

sys.path.insert(0, os.path.abspath('../../')) # path to my_package in my conf.py to make it work.

Unfortunately, I need to delete this line to make it work with readthedocs as suggested here: how to document cython function on readthedocs.

My question is, what is the best practice to build documentation on read the docs and locally with the same code?

read-the-docs creates a venv, pip install requirements, install the cython project and then run sphinx-build.

I would like to avoid doing the same locally because this is time consuming. Is there antoher way? Which one is the best practice?

BlueSheepToken
  • 5,751
  • 3
  • 17
  • 42
  • Always create and use a virtual environment. `venv` is a tool in Python 3 that creates a virtual environment, so one does not "create a venv". Install packages and your project into the virtual environment. Now beyond that, you will get many differing opinions. I would recommend that you find a project that is documented on RTD and that includes documentation for how to build the project's docs locally as well, like almost any project under the Pylons Project, like [Pyramid](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L116-L123), which uses `tox` to run tests and build docs. – Steve Piercy Apr 04 '19 at 08:24
  • @StevePiercy, thank you I am going to check (Actually I would like to avoid creating a virtual env, it is time consuming), but I will check the different projects, thank you very much – BlueSheepToken Apr 04 '19 at 08:26
  • What exactly is time consuming about creating a virtual environment? It's one step: `python3 -m venv env`. It is definitely faster to destroy your system with `sudo pip install many_conflicting_packages` than using a virtual environment, so I'll give you that point. – Steve Piercy Apr 04 '19 at 09:40
  • You are right, I do not have many packages. I will test it out and tell you more once it is done ! :) – BlueSheepToken Apr 04 '19 at 11:05
  • There are lots of ways to install many packages, and I won't go into them all, but `pip install p1 p2 p3 ...` works just fine. – Steve Piercy Apr 04 '19 at 19:39
  • @StevePiercy, if you write an answer, I will accept it. Doing some venv is not that time consuming – BlueSheepToken Apr 05 '19 at 12:06

1 Answers1

1

Always create and use a virtual environment. venv is a tool in Python 3 that creates a virtual environment, so one does not "create a venv". Install packages and your project into the virtual environment.

# create and change working directory
mkdir ~/projects/myproject
cd ~/projects/myproject
# create a virtual environment for your project
python3 -m venv env
# activate the virtual environment
source env/bin/activate
# optionally upgrade packaging tools
pip install --upgrade pip setuptools
# install your package in editable mode into your virtual environment
pip install -e .
# install other packages into your virtual environment
pip install sphinx another_package one_more_package

Now do all your Sphinx stuff and follow the rest of the instructions at the link you provided in your question.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Thanks ! As a side note, I might be using venv wrong, but for me venv is a shortcut for virtual env, isnt it? – BlueSheepToken Apr 06 '19 at 11:11
  • No. These are all different terms with unique definitions and usage. See the Python 3 module [venv](https://docs.python.org/3/library/venv.html), the tool [virtualenv](https://virtualenv.pypa.io/en/latest/), and term [virtual environment](https://docs.python.org/3/glossary.html#term-virtual-environment). "virtual env" with a space is nonsense even though it sounds like the tool. – Steve Piercy Apr 07 '19 at 07:30