[petsc-dev] integrate petsc4py tarball generation with petsc tarball generation

[Satish Balay]

On Mon, 15 Mar 2021, Lisandro Dalcin wrote:

> On Mon, 15 Mar 2021 at 18:26, Satish Balay <balay at mcs.anl.gov> 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