<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><br class=""><div><br class=""><blockquote type="cite" class=""><div class="">Am 25.08.2020 um 17:24 schrieb Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>>:</div><br class="Apple-interchange-newline"><div class=""><div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""><br class="Apple-interchange-newline"><br class=""><blockquote type="cite" class=""><div class="">On Aug 25, 2020, at 9:26 AM, Patrick Sanan <<a href="mailto:patrick.sanan@gmail.com" class="">patrick.sanan@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 18px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><br class="Apple-interchange-newline"><br class=""><blockquote type="cite" class=""><div class="">Am 25.08.2020 um 15:59 schrieb Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>>:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;"><div class=""><br class=""></div> Aren't we likely to keep using sowing to generate the manual pages and then our own scripts to clean them up and add the links for source code HTML etc? But use Sphinx for the users manual and all web pages we maintain ourselves, FAQ etc? </div></div></blockquote><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;"><div class=""><br class=""></div><div class=""> So we will always have two "build" parts for documentation and need to coordinate them?</div></div></div></blockquote>Yes - what I'm hoping for is that we can come up with a process to make sure that the same event triggers updating of both systems. I'm not sure if this is already in the capabilities of the CI system on GitLab - can we, for example, trigger a "classic" docs build whenever master (or whichever branch) is updated?<br class=""></div></div></blockquote><div class=""><br class=""></div> It is too slow now to put into the CI for every branch. Hopefully it will eventually be fast enough. Currently it hasmany bash scripts etc for each file. It also builds everything from scratch, if we make it user dependencies by hooking in a bit of Jed's gmakefile then it will super fast assuming we can keep the previous build around (which is not normally done with the CI but must be possible).</div></div></blockquote>FWIW I think that's what ReadTheDocs does by default, which might make it feasible to build more things there.<br class=""><blockquote type="cite" class=""><div class=""></div></blockquote><blockquote type="cite" class=""><div class=""><div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""><br class=""></div><div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""> Barry</div><div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""><br class=""></div><div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""><br class=""><blockquote type="cite" class=""><div class=""><div class="" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 18px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;"><div class=""><br class=""></div><div class=""> Or do you have a plan to generate the manual pages with some other tool? I don't think that is possible. BTW: I am updating the generation/processing of the manual pages in <span class="" style="font-family: Menlo; font-size: 14px;">barry/2020-07-07/docs-no-makefiles </span> It should be much faster once several rounds of refactorization are done and will not require all the SOURCEC EXAMPLESC stuff in the makefiles anymore.</div><div class=""><br class=""></div></div></div></blockquote>I think the best idea so far is to (once or with each build) parse the sowing syntax into something Sphinx can then parse (that is, reStructuredText), but that seems like a lot of work to undertake when there is lower-hanging fruit in terms of making the docs more usable.</div></div></blockquote><div class=""><br class=""></div> <br class=""><blockquote type="cite" class=""><div class=""><div class="" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 18px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><br class=""></div><div class="" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 18px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">Another option which occurs to me now that you mention you're speeding up the man page build is that, if the full classic docs build were sufficiently fast, it could also be done automatically on the ReadTheDocs server (as a minimal build with docs is done now), and then perhaps we can just use the HTML that's generated on<span class="Apple-converted-space"> </span><a href="http://docs.petsc.org/" class="">docs.petsc.org</a> .<br class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;"><div class=""> Barry</div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""> <br class=""><div class=""><br class=""><blockquote type="cite" class=""><div class="">On Aug 25, 2020, at 8:43 AM, Patrick Sanan <<a href="mailto:patrick.sanan@gmail.com" class="">patrick.sanan@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;">This is still up for debate.<div class=""><br class=""></div><div class="">The main push right now is to try and move as many of the docs as possible (in particular, the users manual) to a web-friendlier format, using Sphinx and ReadTheDocs. Unlike the current "classic" docs at <a href="https://www.mcs.anl.gov/petsc/documentation/index.html" class="">https://www.mcs.anl.gov/petsc/documentation/index.html</a>, this is used in a style very similar to CI - we have a .readthedocs.yml file, and<span class="Apple-converted-space"> </span><a href="http://docs.petsc.org/" class="">docs.petsc.org</a> (linked to our ReadTheDocs account) updates itself whenever things are pushed to master (or other branches we specify).</div><div class=""><br class=""></div><div class="">What makes this a bit ugly at the moment is that a lot of the material, in particular the HTML source code and the man pages, is still built by the classic docs system (nightly). So, there are two subsets of documentation with two different build processes. This is obviously not what we want in the long run, but has the advantage of allowing us to make incremental progress (in my view, the only possible progress) on the docs.</div><div class=""><br class=""></div><div class="">Currently, the Sphinx build actually does a minimal build of PETSc, enough to obtain information to generate man pages links to the "classic" docs.</div><div class=""><div class=""><br class=""><blockquote type="cite" class=""><div class="">Am 24.08.2020 um 19:22 schrieb Fande Kong <<a href="mailto:fdkong.jd@gmail.com" class="">fdkong.jd@gmail.com</a>>:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class=""><div dir="ltr" class=""><div class=""><div class="">Could we support "make docs" instead of "xx-docs-xxx"?</div><div class=""><br class=""></div><div class="">Or were we planning to support multiple formats? </div></div><div class=""><br class=""></div><div class="">Thanks,</div><div class=""><br class=""></div><div class="">Fande,</div><div dir="ltr" class=""><br class=""></div><br class=""><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Aug 21, 2020 at 9:58 AM huabel via petsc-dev <<a href="mailto:petsc-dev@mcs.anl.gov" class="">petsc-dev@mcs.anl.gov</a>> wrote:<br class=""></div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;"><div class="" style="word-wrap: break-word; line-break: after-white-space;"> success to make <span class="" style="font-family: Menlo; font-size: 11px;">sphinx-docs-html</span>. <div class=""> </div><div class="">Thanks!<div class=""><br class=""><div class=""><br class=""><blockquote type="cite" class=""><div class="">On Aug 21, 2020, at 11:40 PM, Satish Balay <<a href="mailto:balay@mcs.anl.gov" target="_blank" class="">balay@mcs.anl.gov</a>> wrote:</div><br class=""><div class=""><div class="">The updates referred in this thread are in master branch [and not maint]<br class=""><br class="">Satish<br class=""><br class="">On Fri, 21 Aug 2020, huabel via petsc-dev wrote:<br class=""><br class=""><blockquote type="cite" class=""><br class="">➜ petsc git:(maint) make sphinx-docs-html<br class="">/usr/local/opt/python@3.8/bin/python3.8 ./config/gmakegen.py --petsc-arch=arch-darwin-c-debug<br class="">/usr/local/opt/python@3.8/bin/python3.8 /Volumes/data3/fun2/demox/petsc/config/gmakegentest.py --petsc-dir=/Volumes/data3/fun2/demox/petsc --petsc-arch=arch-darwin-c-debug --testdir=./arch-darwin-c-debug/tests<br class="">gmake[1]: *** No rule to make target 'sphinx-docs-html'. Stop.<br class="">gmake: *** [GNUmakefile:17: sphinx-docs-html] Error 2<br class=""><br class=""><br class=""><br class=""><blockquote type="cite" class="">On Aug 21, 2020, at 11:06 PM, Jed Brown <<a href="mailto:jed@jedbrown.org" target="_blank" class="">jed@jedbrown.org</a>> wrote:<br class=""><br class="">huabel via petsc-dev <<a href="mailto:petsc-dev@mcs.anl.gov" target="_blank" class="">petsc-dev@mcs.anl.gov</a>> writes:<br class=""><br class=""><blockquote type="cite" class="">Thanks, I copied the ‘developer’ fold out and comment (#extensions.append('sphinxcontrib.bibtex’) this line, with few copy it works well, (no cite link), for me it enough.<span class="Apple-converted-space"> </span><br class=""></blockquote><br class="">We recommend using `make sphinx-docs-html` from the top-level. It will create/activate a virtualenv based on requirements.txt so everything will work. It's fast for incremental updates.</blockquote></blockquote></div></div></blockquote></div></div></div></div></blockquote></div></div></div></div></blockquote></div></div></div></div></blockquote></div></div></div></div></blockquote></div></div></blockquote></div></div></blockquote></div><br class=""></body></html>