> Am 25.08.2020 um 17:24 schrieb Barry Smith <[email protected]>:
>
>
>
>> On Aug 25, 2020, at 9:26 AM, Patrick Sanan <[email protected]
>> <mailto:[email protected]>> wrote:
>>
>>
>>
>>> Am 25.08.2020 um 15:59 schrieb Barry Smith <[email protected]
>>> <mailto:[email protected]>>:
>>>
>>>
>>> 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?
>> 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?
>
> 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).
FWIW I think that's what ReadTheDocs does by default, which might make it
feasible to build more things there.
>
> Barry
>
>
>>>
>>> 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.
>>>
>> 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.
>
>
>>
>> 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 docs.petsc.org <http://docs.petsc.org/> .
>>> Barry
>>>
>>>
>>>
>>>
>>>> On Aug 25, 2020, at 8:43 AM, Patrick Sanan <[email protected]
>>>> <mailto:[email protected]>> 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 <[email protected]
>>>>> <mailto:[email protected]>>:
>>>>>
>>>>> 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
>>>>> <[email protected] <mailto:[email protected]>> wrote:
>>>>> success to make sphinx-docs-html.
>>>>>
>>>>> Thanks!
>>>>>
>>>>>
>>>>>> On Aug 21, 2020, at 11:40 PM, Satish Balay <[email protected]
>>>>>> <mailto:[email protected]>> 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/[email protected]/bin/python3.8 ./config/gmakegen.py
>>>>>>> --petsc-arch=arch-darwin-c-debug
>>>>>>> /usr/local/opt/[email protected]/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 <[email protected]
>>>>>>>> <mailto:[email protected]>> wrote:
>>>>>>>>
>>>>>>>> huabel via petsc-dev <[email protected]
>>>>>>>> <mailto:[email protected]>> 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.
