On Mon, 15 Mar 2021, Lisandro Dalcin wrote:

On Mon, 15 Mar 2021 at 18:26, Satish Balay <[email protected]> wrote:

...

But epydoc can be installed with python3.

Maybe. Have you tried to actually run it after installation? :-)

I have not (yet).

...

So this is more of petsc4py code that uses epydoc - than epydoc code?

I did not understand your question. Epidoc is just an external tool required to build a piece of the documentation. It only runs on Python 2. And to build documentation, it uses introspection, so whatever you want to document has to be installed alongside with epydoc such that epidoc is able to "import petsc4py.PETSc" and proceed to generate the API reference by traversing classes, methods, functions, etc.

...

...

I have not found a nice replacement for epydoc-generated documentation. If Python 2 is an annoyance, then just remove, comment-out anything related to epydoc in "makefile"

Well I can work around it. [by installing both python2 and python3 versions of epydoc via pip]

Don't bother about installing Epydoc in Python 3, it does not work. You only need it in Python 2, also install petsc4py, run "make install py=2" (petsc4py will go to ~/.local)

Ah - its about docutils.

...

...

...

...

checkdocutils: @${PYTHON} -c $$'try:\n import docutils\nexcept:\n print("Run python -m pip install docutils and then try this command again");exit(1)' @${PYTHON2} -c $$'try:\n import docutils\nexcept:\n print("Run python2 -m pip install docutils or pip2 install docutils or [sudo] easy_install docutils and then try the command again");exit(1)' @${PYTHON2} -c $$'try:\n import epydoc\nexcept:\n print("Run python2 -m pip install epydoc or pip2 install epydoc or [sudo] easy_install epydoc and then try the command again");exit(1)' <<<<<

I guess I should do 'make PYTHON=python2 PYTHON=python2' to prevent these checks from running with python3 [and prompting me to install these packages with python3]

...

However its not clear to me where the python2 requirement is coming from - and if things can be unified using python3

I hope it is clear now. A piece of the documentation requires epydoc, which in turns only works on Python 2.

...

...

and run "make sdist".

Ah - ok. Will check this to see if I can generate the tarball in sync with petsc tarball. What source files need updating for release/version info?

CHANGES.rst (add entry for new release)

Can we add a ref to src/docs/website/documentation/changes/index.html from here so that this doesn't need updating?

src/__init__.py (update __version__ to "3.15.0" )

I can update this release version (3.15,3.16 etc) manually for every release in sync with petsc - and automate the patchlevel [again in sync with petsc] One issue: what version do we use here for development snapshot? [Ideally we would somehow automate this to use petscversion.h - that works from git]

$ git grep "PETSc Users Manual" DESCRIPTION.rst: *PETSc Users Manual*, ANL-95/11 - Revision 3.14, 2020. docs/index.rst: *PETSc Users Manual*, ANL-95/11 - Revision 3.14, 2020. docs/source/citing.rst: *PETSc Users Manual*, ANL-95/11 - Revision 3.14, 2020. docs/source/overview.rst: *PETSc Users Manual*, ANL-95/11 - Revision 3.14, 2020.

Ok - I can add these to the list that I update manually (at 3.15,13.16 etc versions)

...

...

But this way the tarball will miss the API reference.

...

PS: All this could be converted to a script that installs petsc4py and epydoc in a Python 2 virtual environment, and next users another venv for the Python 3 Sphinx stuff.

One issue: Fedora-33 does not have 'python2-pip' anymore. I was able to manually install it. However this might become an issue for others who want to build docs [even if we automate the docs build to install/use pyton2-venv]

Yes, Satish I know. The long term solution is to get rid of Epydoc and replace it for something else, most likely Sphinx-based.

Yes - I think this is the long term goal.

If generating this epydoc stuff is too much of an annoyance for you, just kill it for good and let's forget about it.

I'm trying to figure out the appropriate way to integrate this into the petsc tarball build process [that works on my laptop]. I think I have the relevant info now. Making petsc4py doc-gen more portable and more integrated into petsc doc gen process can be improved separately [later] Satish