<html><head><meta http-equiv="Content-Type" content="text/html; charset=us-ascii"></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 07.03.2021 um 01:01 schrieb Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>>:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html; charset=us-ascii" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><br class=""><div class=""><br class=""><blockquote type="cite" class=""><div class="">On Mar 6, 2021, at 4:46 PM, Jed Brown <<a href="mailto:jed@jedbrown.org" class="">jed@jedbrown.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="">The one value-add that comes from ReadTheDocs is its version switcher, which we'd need to do ourselves.<br class=""></div></div></blockquote><div class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div class=""><br class="">I've been using this strategy (for stand-alone preview) on a different project and it's working great. We can decide how to merge it (i.e., where the doc job should run).<br class=""><br class=""><a href="https://gitlab.com/petsc/petsc/-/merge_requests/3523" class="">https://gitlab.com/petsc/petsc/-/merge_requests/3523</a><br class=""></div></div></blockquote><div class=""><br class=""></div> This seems fine if it builds all the docs, manual pages, HTML of source code etc. But it doesn't seem to have anything to do with ReadTheDocs? It is not worth arguing over whether this special build takes place on a cloud machine or an MCS machine IMHO; the only question is where the resulting hundreds of megabytes of webpages end up. Can we just have them as artifacts on <a href="http://gitlab.com/petsc/petsc" class="">gitlab.com/petsc/petsc</a> ? I am fine with that if it works.<br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class="">I think we should run <a href="https://petsc.org/" class="">https://petsc.org</a> from docs generated on main using Sphinx.</div></div></blockquote><div class=""><br class=""></div> I think Satish's question is what about after a release? Does <a href="https://petsc.org/" class="">https://petsc.org</a> point to docs built from release or main? Some users will want release but others will want main. Currently I think we have tricks that use a combination of information from both in a couple of places.</div><div class=""><br class=""></div><div class=""> What about all the other parts of docs not built using Spinx, manual pages, html source? </div><div class=""><br class=""><blockquote type="cite" class=""><div class=""><div class=""> We can link to the old site for older versions. I'd be in favor of making <a href="https://mcs.anl.gov/petsc" class="">https://mcs.anl.gov/petsc</a> (but not its subdirectories) redirect to <a href="http://petsc.org/" class="">petsc.org</a>.<br class=""></div></div></blockquote><div class=""><br class=""></div> That seems ok to me; but will we need to retrain Google, currently it knows which is the "best" webpage for everything in PETSc (like KSPSolve etc) as being at <a href="http://www.mcs.anl.gov/petsc" class="">www.mcs.anl.gov/petsc</a>/... so we need to update the docs to start from <a href="https://petsc.org/" class="">https://petsc.org/</a> </div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""> We need to start making decisions. They seem to be </div><div class=""><br class=""></div><div class="">1) On what physical system are all the docs, Spinx, manual pages, html source actually existing on? </div><div class=""><br class=""></div><div class=""> Choices? <a href="http://gitlab.com/" class="">gitlab.com</a> (as artifacts or something else), ReadTheDocs (can it handle storing the the non-Spinx?), ANL (drawback, only someone with an account can get them onto the system), something else?</div></div></div></blockquote><div><br class=""></div>As far as I can tell so far, RTD can handle the extra HTML pages (my current WIP builds them all, but doesn't move them over to the final location - that might be slow and I don't know if there's a size limit I didn't read about yet). </div><div><br class=""></div><div>One thing RTD gives us (I think) is a nicer search feature. That's been quite useful for me searching the docs, e.g. </div><div><a href="https://docs.petsc.org/en/latest/search/?q=pc_type" class="">https://docs.petsc.org/en/latest/search/?q=pc_type</a></div><div><br class=""></div><div>There are definite downsides to not having as much control, though.</div><div><br class=""></div><div><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><div class=""><br class=""></div><div class="">2) How are all the docs (Spinx and not) built to go into the physical system they will be on?</div><div class=""><br class=""></div><div class=""> Choices? <a href="http://gitlab.com/" class="">gitlab.com</a> (nice, since anyone can trigger their building), ReadTheDocs (again nice that anyone can trigger their building, but can they do the non-Spinx easily?), ANL machine (bad, since requires someone with an account to trigger their build and/or storage). something else?</div></div></div></blockquote><div><br class=""></div>My personal jury is still out on how easy it can be to do the complete build on RTD (see WIP MR <a href="https://docs.petsc.org/en/latest/search/?q=pc_type" class="">https://docs.petsc.org/en/latest/search/?q=pc_type</a>). <br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><div class=""><br class=""></div><div class="">3) Does the default point completely to docs built on release? Or built on main? Or built on some strange combination? </div><div class=""><br class=""></div><div class="">Regardless of these questions I think we agree <a href="https://petsc.org/" class="">https://petsc.org/</a> (and <a href="https://mcs.anl.gov/petsc" class="">https://mcs.anl.gov/petsc</a> by linking) will be how people find the docs. </div><div class=""><br class=""></div></div></div></blockquote>Yes, though maybe It's tempting to build at <a href="http://mcs.anl.gov/petsc" class="">mcs.anl.gov/petsc</a> so that pages with the same content could even have the same URLs, which would be nice for any external links that exist, and search engines' data on the man pages.<br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><div class=""><br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class="">Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>> writes:<br class=""><br class=""><blockquote type="cite" class=""> Is the plan still to use ReadTheDocs (which does support multiple versions of all the docs) or to "build them ourselves"? All ReadTheDocs does is run a Sphinx document builder script the user provides and we can do that ourselves and don't need ReadTheDocs to do it for us. In fact, if we do it ourselves we have much more flexibility since you ware not restricted to running only a Sphinx document builder script.<br class=""><br class=""> Patrick, Jacob and others have done a fantastic job moving a lot of material into much better pages, it seems nuts not to be using it all.<br class=""><br class=""> Barry<br class=""><br class=""><br class=""><blockquote type="cite" class="">On Mar 6, 2021, at 12:33 PM, Satish Balay <<a href="mailto:balay@mcs.anl.gov" class="">balay@mcs.anl.gov</a>> wrote:<br class=""><br class="">This is partly due to the complexity of having some docs from 'release' and some from 'main' branches.<br class=""><br class="">We had a way to manage this when all docs were on petsc website - but its not clear how to do this properly with readthedocs<br class=""><br class="">Satish<br class=""><br class="">On Fri, 5 Mar 2021, Barry Smith wrote:<br class=""><br class=""><blockquote type="cite" class=""><br class=""> What is the plan to transition to the new documentation and webpages?<br class=""><br class=""> I go to <a href="https://www.mcs.anl.gov/petsc/index.html" class="">https://www.mcs.anl.gov/petsc/index.html</a> <<a href="https://www.mcs.anl.gov/petsc/index.html" class="">https://www.mcs.anl.gov/petsc/index.html</a>> and mostly see the old stuff etc. Our next release is coming up soon and it would be nice to have transitioned out of the old material and to the new material by/at the new release.<br class=""><br class=""> What do we need to do to make this happen?<br class=""><br class=""> Thanks<br class=""><br class=""> Barry<br class=""><br class=""><br class=""></blockquote><br class=""></blockquote></blockquote></div></div></blockquote></div><br class=""></div></div></blockquote></div><br class=""></body></html>