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 <[email protected]>:
>
> 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: [email protected] <mailto:[email protected]>
> 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 <[email protected]
>> <mailto:[email protected]>> 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)
>>
>
