Update Build Instructions for Pipenv

[Oglopf]

It looks like a change was made upstream by pipenv that now uses plette for some checking that is not working with our Pipfile.

You can read the issue here, where the user has the same error you get using rake pipenv:install currently: https://github.com/pypa/pipenv/discussions/5370

To fix this, just add the following to the Rakefile:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = 'pypi'
...

And this got things moving forward. Will create a PR shortly once I'm sure all parts work right.

┆Issue is synchronized with this Asana task by Unito

[Oglopf]

Moving further along and seeing more problems.

When issuing rake pipenv:build the following exception occurs:

Could not import extension sphinx.builders.latex (exception: cannot import name 'contextfunction' from 'jinja2' (/home/trav/dvlmnt/ood-documentation/.venv/lib/python3.10/site-packages/jinja2/__init__.py))

So now the question is whether I'm using the correct version of Sphinx and it's dependencies (Jinja2 is installed during the pip3 install Sphinx command below). But I can't find any requirements in the repo for this.

Also, to even get this far one would have to have ran pip3 install Sphinx as well, which we should also include as a step in the build.

Current setup:

ubuntu   22.04
python   3.10
pip3     22.0.2
pipenv   2022.11.30
Jinja2   3.1.2
Sphinx   5.3.0

I'm going to play with these dependencies since I can just pip3 uninstall/install <software>==<version> them to see what I can get to match up and give a working build (hopefully :crossed_fingers: ).

[Oglopf]

In order for the docs to have the right versions, you need to activate the actual venv with the pipenv shell command, which should be added as a rake task as well if we provide one already for some of this. Something like:

rake pipenv:activate_env

With the easy addition of the following task in the Rakefile:

namespace :pipenv do
...
  desc "Start pipenv shell and correct python version to build docs"
  task :activate_env do
    exec 'WORKDIR=/doc PIPENV_VENV_IN_PROJECT=1 pipenv shell'
    exec 'pipenv install --python 2.7'
    exec 'pipenv --python 2.7'
  end
...
end

Once setting the shell up correctly I then had to still clear the error due to a change in jinja2 for a method name from contextfunction to context_pass in jinja2 versions >= 3.0.0.

So, building this with the Jinja2 version set to 2.10.1 still satisfies security requirement in the Pipfile it is under and moved things along again.

[Oglopf]

I'm guessing overall the use of >= for depencies needs checked as the next error is similar:

ImportError: cannot import name 'soft_unicode' from 'markupsafe'

I'll have to see what is pulling this in as it is likely a problem with the various >= being set in the Pipfile for:

requests = ">=2.20.0"
urllib3 = ">=1.24.2"

[Oglopf]

Looks like the version of markupsafe is what needs controlled here. Build moved forward with:

markupsafe==2.0.1

While previously it would not work with 2.1.1.

[Oglopf]

Ultimately the pipenv setup was very broken and given we already have a simple container method to build the docs, we should remove these instructions.

It is also easier for us as we know have one way to build, using containers, which will be much easier for users and maintainers.