[petsc-dev] Users manual update

[Barry Smith]

  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? 

  So we will always have two "build" parts for documentation and need to coordinate them?

  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 barry/2020-07-07/docs-no-makefiles  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.

  Barry


  

> On Aug 25, 2020, at 8:43 AM, Patrick Sanan <patrick.sanan at gmail.com> wrote:
> 
> This is still up for debate.
> 
> 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 https://www.mcs.anl.gov/petsc/documentation/index.html <https://www.mcs.anl.gov/petsc/documentation/index.html>, this is used in a style very similar to CI - we have a .readthedocs.yml file, and docs.petsc.org <http://docs.petsc.org/> (linked to our ReadTheDocs account) updates itself whenever things are pushed to master (or other branches we specify).
> 
> 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.
> 
> Currently, the Sphinx build actually does a minimal build of PETSc, enough to obtain information to generate man pages links to the "classic" docs.
> 
>> Am 24.08.2020 um 19:22 schrieb Fande Kong <fdkong.jd at gmail.com <mailto:fdkong.jd at gmail.com>>:
>> 
>> Could we support "make docs" instead of "xx-docs-xxx"?
>> 
>> Or were we planning to support multiple formats? 
>> 
>> Thanks,
>> 
>> Fande,
>> 
>> 
>> On Fri, Aug 21, 2020 at 9:58 AM huabel via petsc-dev <petsc-dev at mcs.anl.gov <mailto:petsc-dev at mcs.anl.gov>> wrote:
>>   success to make sphinx-docs-html. 
>>   
>> Thanks!
>> 
>> 
>>> On Aug 21, 2020, at 11:40 PM, Satish Balay <balay at mcs.anl.gov <mailto:balay at mcs.anl.gov>> wrote:
>>> 
>>> The updates referred in this thread are in master branch [and not maint]
>>> 
>>> Satish
>>> 
>>> On Fri, 21 Aug 2020, huabel via petsc-dev wrote:
>>> 
>>>> 
>>>> ➜  petsc git:(maint) make sphinx-docs-html
>>>> /usr/local/opt/python at 3.8/bin/python3.8 ./config/gmakegen.py --petsc-arch=arch-darwin-c-debug
>>>> /usr/local/opt/python at 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
>>>> gmake[1]: *** No rule to make target 'sphinx-docs-html'.  Stop.
>>>> gmake: *** [GNUmakefile:17: sphinx-docs-html] Error 2
>>>> 
>>>> 
>>>> 
>>>>> On Aug 21, 2020, at 11:06 PM, Jed Brown <jed at jedbrown.org <mailto:jed at jedbrown.org>> wrote:
>>>>> 
>>>>> huabel via petsc-dev <petsc-dev at mcs.anl.gov <mailto:petsc-dev at mcs.anl.gov>> writes:
>>>>> 
>>>>>> 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. 
>>>>> 
>>>>> 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.
>>>> 
>>>> 
>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20200825/d57675d5/attachment-0001.html>