<div dir="ltr"><div>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 <a href="http://petsc.org/release/developers/documentation">petsc.org/release/developers/documentation</a>, 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.</div><div><br></div><div>On to tip #1 !</div><div><br></div><div>What happens when you build the docs locally by following our instructions? What files are generated and can I delete them?<br></div><div><br></div><div>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!).</div><div><div><a href="https://petsc.org/release/developers/documentation/#building-the-html-docs-locally">https://petsc.org/release/developers/documentation/#building-the-html-docs-locally</a></div></div><div><br></div><div>1. doc/makefile calls sphinx-build<br></div><div>2. sphinx-build looks at doc/conf.py and searches the whole doc/ tree for .rst files</div><div>3. It then uses the html builder to generate _build/html . <br></div><div>4. You open _build/html/index.html<br></div><div><br></div><div>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:</div><div><br></div><div>1. With a custom extension in doc/ext, relying on the classic "htmlmap" file<br></div><div>2. With some custom hooks defined at the end of conf.py</div><div><br></div><div>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.<br></div><div><br></div><div>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 <a href="http://gitlab.com/petsc/images">gitlab.com/petsc/images</a> . <br></div><div><br></div><div>So, I end up with these untracked directories:<br></div><div><br></div><div>doc/_build <br></div><div>    Sphinx's output directory. Can be generated quite quickly, so delete whenever you'd like. "make clean" in doc/ deletes this.<br></div><div><br></div><div>doc/_build_classic</div><div>    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.<br></div><div><br></div><div>doc/images</div><div>    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.</div><div><br></div><div>arch-classic-docs</div><div>    Delete as desired, but in general you shouldn't need to.<br></div><div><br></div><br><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div></div>