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.a...@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.troff...@gmail.com <mailto:matthias.troff...@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.sa...@gmail.com >> <mailto:patrick.sa...@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) >> >