fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 23 May 2011 16:28, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>
>
> On 23/05/11 15:23, Marie E. Rognes wrote:
>> On 05/23/2011 04:10 PM, Garth N. Wells wrote:
>>>
>>>
>>> On 23/05/11 14:57, Marie E. Rognes wrote:
>>>> On 05/23/2011 03:26 PM, Garth N. Wells wrote:
>>>>> I think we need figure out quickly how to build the doc now that it's
>>>>> been moved into the source tree (at least for DOLFIN). Has anyone given
>>>>> this some thought?
>>>>
>>>> Some :-)
>>>>
>>>>> Is the idea to add a root file to dolfin/doc, and
>>>>> just use paths relative to this to include demo doc, programmer ref,
>>>>> etc?
>>>>
>>>> I put the demo doc (.rst) together with the demos (common text in
>>>> common dir, cpp/python specific .rst in cpp/python dirs). This makes
>>>> it natural to update the doc when updating the demo code, and seemed
>>>> like the most intuitive to me.
>>>>
>>>
>>> Are you saying that we should include one .rst file in another .rst file
>>> using paths that follow the DOLFIN directory structure?
>>
>>
>> Not exactly. I'm saying that demo/foo/cpp/documentation.rst and
>> demo/foo/python documentation.rst includes demo/foo/common.txt (as
>> ../common.txt). This is as it was in fenics-doc with the exception that
>> the code for the demos was copied from dolfin using a separate script.
>>
>
> That bit's easy, but the next level up needs to include the demo files.
>
>>
>>>
>>>> Next planned step is to move the programmer's-reference-generating
>>>> scripts from fenics-doc, and let these generate the .rst-files under
>>>> for instance dolfin/doc.
>>>>
>>>>> Should the doc be built in the CMake 'build' dir?
>>>>
>>>> Is "the doc" the .rst or the .html?
>>>>
>>>
>>> I think we should let CMake do whatever it wants when it builds the
>>> files (which is create the html files in the build dir), and have CMake
>>> install the html/pdf files in share/dolfin/doc.
>>
>> Fine by me.
>>
>> Should the generation of the programmer's reference (from code to .rst)
>> also be a part of the build or should it be explicitely generated and
>> stored (like the swig-generated files)?
>>
>
> I would suggest that it be built by the user, and when making a release
> we can consider building and including it then. Otherwise we'll fill the
> repository with html files.

I agree that we shouldn't include html files anywhere, but the .rst
files for the programmer's reference should be re-generated by any
developer who changes the interface. Just like we let the 'make test'
check if the demo code in the documentation is correct.

Kristian

> Garth
>
>> --
>> Marie
>>
>>>
>>> Garth
>>>
>>>>> The next question is then how best to pull the docs together for the
>>>>> web page.
>>>>
>>>> My initial suggestion would be
>>>>
>>>> 1. Copy .rst from dolfin/doc and dolfin/demos
>>>> 2. Generate small layer of .rst's integrating these with web page
>>>> 3. Build.
>>>>
>>>> --
>>>> Marie
>>>>
>>>> _______________________________________________
>>>> Mailing list: https://launchpad.net/~fenics
>>>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>>>> Unsubscribe : https://launchpad.net/~fenics
>>>> More help   : https://help.launchpad.net/ListHelp
>>>
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~fenics
>>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~fenics
>>> More help   : https://help.launchpad.net/ListHelp
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>