[petsc-dev] plan to transition to new documentation and webpages?

[Barry Smith]

  I think it is time to stop completely distributing docs with tarballs. Most people don't know they are there and how to access them so use google anyways. 

  Also we should build release docs on release and main docs on main and forget the headaches of trying to put some new stuff in with the old.

  Then the only thing the tarball includes besides what is in git is the Fortran, petsc4py?  interfaces. Has there been any issues with sowing bfort support portability in many years?  petsc4py must need cpython, but does it need it for the tarball or is all of that pre-built when the tarball is made?

   I would advocate trying a release where the tarball is the git repository and see what happens. The current API says users would need to use --download-sowing but we could automatically turn that on if Fortran interfaces are requested. If we have tons of error reports with sowing we could revert and put the Fortran stubs back in. (Windows might be a problematic system).

   Time to clean house and simplify,

  Barry




> On Mar 7, 2021, at 2:01 PM, Satish Balay <balay at mcs.anl.gov> wrote:
> 
> Some notes on previous organization:
> 
> - We have separate docs (manual, manpages, etc) for each petsc release
> https://www.mcs.anl.gov/petsc/petsc-3.14/docs/
> https://www.mcs.anl.gov/petsc/petsc-main/docs/
> - the website (including developer docs, faq etc) primarily was built from 'main' branch.
>  Only the following website docs were synced from 'release' branch:
>  * documentation/index.html
>  * documentation/installation.html
>  * exclude=download/index.html
> - All the website docs are also part of the release tarball (formatted differently),
> so these versions are also available [perhaps this part needs preserving]
> https://www.mcs.anl.gov/petsc/documentation/installation.html
> vs
> https://www.mcs.anl.gov/petsc/petsc-3.12/docs/installation.html
> 
> Satish
> 
> 
> On Sun, 7 Mar 2021, Patrick Sanan wrote:
> 
>> Here's my WIP on having the sphinx build include a consistent set of HTML pages from the "classic" docs build.
>> https://gitlab.com/petsc/petsc/-/merge_requests/3684 <https://gitlab.com/petsc/petsc/-/merge_requests/3684>
>> 
>> 
>> 
>>> Am 07.03.2021 um 08:37 schrieb Patrick Sanan <patrick.sanan at gmail.com>:
>>> 
>>> I'm working on this right now - I think I have a workable way, where we just use the "classic" docs system to build the man pages and HTML sources for each version on RTD, and then specify those HTML files as "extra" to Sphinx, so it just copies them over in the build and we can refer to them with local links (and their internal relative links work). Hopefully I can have a demo in the next couple of days.
>>> 
>>>> Am 06.03.2021 um 19:33 schrieb Satish Balay via petsc-dev <petsc-dev at mcs.anl.gov>:
>>>> 
>>>> 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> 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
>>>>> 
>>>>> 
>>>> 
>>> 
>> 
>> 
>