[petsc-dev] Users manual update

[Patrick Sanan]

Note that we have only tested things with Sphinx 2.4.4, because we rely on a custom extension to add the links to man pages. 

We recently added a helper target in the top-level makefile, which sets up a virtual environment for you with the same packages used for the ReadTheDocs build. Perhaps you can try that, or it can give a hint as to how to set up your own Python environment?

    cd $PETSC_DIR
    make sphinx-docs-clean
    make sphinx-docs-html
    open src/docs/sphinx_docs/_build/html/index.html



> Am 21.08.2020 um 10:39 schrieb huabel <hu.ds.abel at icloud.com>:
> 
> Hi 
>   I run make dirhtml get some error
> 
> ➜  sphinx_docs git:(maint) make dirhtml
> Running Sphinx v3.1.2
> 
> Found DOT install: /usr/local/bin/dot
> 
> 
> Extension error:
> Could not import extension sphinxcontrib.bibtex (exception: No module named 'sphinxcontrib.bibtex')
> gmake: *** [Makefile:29: dirhtml] Error 2
> ➜  sphinx_docs git:(maint) pip3 show sphinxcontrib-bibtex
> Name: sphinxcontrib-bibtex
> Version: 1.0.0
> Summary: A Sphinx extension for BibTeX style citations.
> Home-page: https://github.com/mcmtroffaes/sphinxcontrib-bibtex <https://github.com/mcmtroffaes/sphinxcontrib-bibtex>
> Author: Matthias C. M. Troffaes
> Author-email: matthias.troffaes at gmail.com <mailto:matthias.troffaes at gmail.com>
> License: BSD
> Location: /usr/local/lib/python3.8/site-packages
> Requires: oset, Sphinx, pybtex-docutils, pybtex
> Required-by: 
> ➜  sphinx_docs git:(maint) brew info graphviz
> graphviz: stable 2.44.1 (bottled), HEAD
> Graph visualization software from AT&T and Bell Labs
> https://www.graphviz.org/ <https://www.graphviz.org/>
> /usr/local/Cellar/graphviz/2.44.1 (506 files, 18MB) *
>   Poured from bottle on 2020-07-12 at 16:47:06
> From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/graphviz.rb <https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/graphviz.rb>
> License: EPL-1.0
> ==> Dependencies
> Build: autoconf ✔, automake ✘, pkg-config ✔
> Required: gd ✔, gts ✔, libpng ✔, libtool ✔, pango ✘
> ==> Options
> --HEAD
> 	Install HEAD version
> ==> Analytics
> install: 59,114 (30 days), 157,762 (90 days), 518,413 (365 days)
> install-on-request: 48,388 (30 days), 125,480 (90 days), 390,556 (365 days)
> build-error: 0 (30 days)
> 
> 
> 
>> On Aug 21, 2020, at 3:14 PM, Patrick Sanan <patrick.sanan at gmail.com <mailto:patrick.sanan at gmail.com>> wrote:
>> 
>> Hi all - 
>> 
>> We're working on getting the users manual fully migrated to Sphinx, so we can delete the pure-LaTeX version.
>> 
>> So far, we've done most of the groundwork to set things up using Sphinx and ReadTheDocs, and to do some semi-automated conversion of the manual. Most people will access the manual via docs.petsc.org <http://docs.petsc.org/>, but Sphinx also allows you to build a PDF (via LaTeX) of the docs, which we'll maintain so as to have something citable.
>> 
>> Most sections of the manual have a big ugly warning asking for volunteers, e.g. here: https://docs.petsc.org/en/latest/manual/mat/ <https://docs.petsc.org/en/latest/manual/mat/> . An expert reading through any of the chapters will certainly find things they can fix or remove as they go through. That said, the main objective for now is simply to provide the existing content in a web-friendly way. The minimal task mostly involves fixing references and tables (use list-table whenever possible). 
>> 
>> Probably the best example so far of good formatting is the SNES chapter which Jed has been working on:
>> https://docs.petsc.org/en/latest/manual/snes/ <https://docs.petsc.org/en/latest/manual/snes/> 
>> 
>> Regarding Sphinx, tips and useful conventions are being noted here:
>> https://docs.petsc.org/en/latest/developers/documentation/#sphinx-documentation-guidelines <https://docs.petsc.org/en/latest/developers/documentation/#sphinx-documentation-guidelines>
>> 
>> (Note that for small docs changes like this, you can go to the ReadTheDocs drop-down in the bottom right and click a link to directly edit on GitLab)
>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20200821/54c7dabd/attachment.html>