[petsc-dev] [DocTip!] #1 : What does the docs build build? What can I delete?

[Patrick Sanan]

This is an experiment to try to disseminate information about the docs.
Things here will be less formal and more practical than what might be at
petsc.org/release/developers/documentation, and importantly, because this
is a mailing list, I can describe things that will go out of date as we
improve the docs but is nonetheless useful to current development.

On to tip #1 !

What happens when you build the docs locally by following our instructions?
What files are generated and can I delete them?

The basic instructions are here (Bonus tip: make sure you don't
accidentally put petsc-docs-env inside of doc/, as that will greatly
confuse Sphinx as it locates its own .rst files!).
https://petsc.org/release/developers/documentation/#building-the-html-docs-locally

1. doc/makefile calls sphinx-build
2. sphinx-build looks at doc/conf.py and searches the whole doc/ tree for
.rst files
3. It then uses the html builder to generate _build/html .
4. You open _build/html/index.html

That's not the whole story, though, because we still rely on the "classic"
docs system which has a lot of useful logic we haven't made more
Sphinx/python native yet. This is controlled in two ways:

1. With a custom extension in doc/ext, relying on the classic "htmlmap" file
2. With some custom hooks defined at the end of conf.py

Because of these, when you run sphinx-build, PETSc itself will be
configured as minimally as possible to run "make alldoc12", and you'll end
up with an arch-classic-docs directory and a doc/_build_classic directory .
You'll see (lots of) additional output due to this configuration, and some
banners at the end of the build as the generated files are copied and
placeholder relative links required by the extension are resolved.

That's still not the whole story, though, because we have a special, "add
files only", images repository. Thus, in doc/makefile, you'll see very
simple logic which does a Git clone to populate doc/images from
gitlab.com/petsc/images .

So, I end up with these untracked directories:

doc/_build
    Sphinx's output directory. Can be generated quite quickly, so delete
whenever you'd like. "make clean" in doc/ deletes this.

doc/_build_classic
    Output for the classic docs build. Delete when desired, but realize
that regenerating it can be slow, so only do so if e.g. you've changed the
man pages. "make clean" in doc/ also deletes this.

doc/images
    Will not currently be updated in any intelligent way, so if you have
images issues, make sure you haven't got any of your own new stuff in here,
delete it, and let it be re-cloned.

arch-classic-docs
    Delete as desired, but in general you shouldn't need to.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20211103/c9006977/attachment.html>