> Am 07.03.2021 um 01:01 schrieb Barry Smith <[email protected]>: > > > >> On Mar 6, 2021, at 4:46 PM, Jed Brown <[email protected] >> <mailto:[email protected]>> wrote: >> >> The one value-add that comes from ReadTheDocs is its version switcher, which >> we'd need to do ourselves. > >> >> 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). >> >> https://gitlab.com/petsc/petsc/-/merge_requests/3523 >> <https://gitlab.com/petsc/petsc/-/merge_requests/3523> > > 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 gitlab.com/petsc/petsc <http://gitlab.com/petsc/petsc> ? I am fine with > that if it works. >> >> I think we should run https://petsc.org <https://petsc.org/> from docs >> generated on main using Sphinx. > > I think Satish's question is what about after a release? Does > https://petsc.org <https://petsc.org/> 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. > > What about all the other parts of docs not built using Spinx, manual > pages, html source? > >> We can link to the old site for older versions. I'd be in favor of making >> https://mcs.anl.gov/petsc <https://mcs.anl.gov/petsc> (but not its >> subdirectories) redirect to petsc.org <http://petsc.org/>. > > 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 www.mcs.anl.gov/petsc <http://www.mcs.anl.gov/petsc>/... so we need > to update the docs to start from https://petsc.org/ <https://petsc.org/> > > > We need to start making decisions. They seem to be > > 1) On what physical system are all the docs, Spinx, manual pages, html > source actually existing on? > > Choices? gitlab.com <http://gitlab.com/> (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?
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). One thing RTD gives us (I think) is a nicer search feature. That's been quite useful for me searching the docs, e.g. https://docs.petsc.org/en/latest/search/?q=pc_type <https://docs.petsc.org/en/latest/search/?q=pc_type> There are definite downsides to not having as much control, though. > > 2) How are all the docs (Spinx and not) built to go into the physical system > they will be on? > > Choices? gitlab.com <http://gitlab.com/> (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? My personal jury is still out on how easy it can be to do the complete build on RTD (see WIP MR https://docs.petsc.org/en/latest/search/?q=pc_type <https://docs.petsc.org/en/latest/search/?q=pc_type>). > > 3) Does the default point completely to docs built on release? Or built on > main? Or built on some strange combination? > > Regardless of these questions I think we agree https://petsc.org/ > <https://petsc.org/> (and https://mcs.anl.gov/petsc > <https://mcs.anl.gov/petsc> by linking) will be how people find the docs. > Yes, though maybe It's tempting to build at mcs.anl.gov/petsc <http://mcs.anl.gov/petsc> 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. > >> >> Barry Smith <[email protected] <mailto:[email protected]>> writes: >> >>> 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. >>> >>> 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. >>> >>> Barry >>> >>> >>>> On Mar 6, 2021, at 12:33 PM, Satish Balay <[email protected] >>>> <mailto:[email protected]>> wrote: >>>> >>>> This is partly due to the complexity of having some docs from 'release' >>>> and some from 'main' branches. >>>> >>>> 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 >>>> >>>> Satish >>>> >>>> On Fri, 5 Mar 2021, Barry Smith wrote: >>>> >>>>> >>>>> What is the plan to transition to the new documentation and webpages? >>>>> >>>>> I go to https://www.mcs.anl.gov/petsc/index.html >>>>> <https://www.mcs.anl.gov/petsc/index.html> >>>>> <https://www.mcs.anl.gov/petsc/index.html >>>>> <https://www.mcs.anl.gov/petsc/index.html>> 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. >>>>> >>>>> What do we need to do to make this happen? >>>>> >>>>> Thanks >>>>> >>>>> Barry >>>>> >>>>> >>>> >
