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

[Lisandro Dalcin]

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? :-)


> 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)


>
> 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)
src/__init__.py (update __version__ to "3.15.0" )


$ 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.


> > 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.
If generating this epydoc stuff is too much of an annoyance for you, just
kill it for good and let's forget about it.


-- 
Lisandro Dalcin
============
Senior Research Scientist
Extreme Computing Research Center (ECRC)
King Abdullah University of Science and Technology (KAUST)
http://ecrc.kaust.edu.sa/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20210315/96c3a575/attachment.html>