fenics team mailing list archive

["Garth N. Wells" <gnw20@xxxxxxxxx>]

On 23/05/11 15:42, Marie E. Rognes wrote:
> On 05/23/2011 04:28 PM, Garth N. Wells 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.
> 
> I don't understand. Next level up in what direction?
> 

The top level, and from there down, e.g.

dolfin/doc/documentation.rst

   .. toctree::

      path/to-prog/ref
      ../demo/demos.rst
      .
      .

>>
>>>
>>>>
>>>>> 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.
> 
> To clarify, I'm thinking of a two-step pipeline
> 
>         (1)     (2)
>    Code -> .rst -> .html
> 
> Details to be sorted out:
> 
> 1. When and how should step (1) happen?
> 2. Should (if yes, where) .rst be stored in the repository?
> 3. When and how should step (2) happen?
> 
> One way would be
> 
> 1. Explicitely by someone running a generate-script
> 2. Yes, under dolfin/doc
> 3. As you suggest above (with some basic default settings from sphinx)
> 

It should run via the build system, with make targets for each step. The
build system can test that Sphinx is available and is the correct version.


> Further:
> 
> 4. The official web page either has its own version of steps 1 -- 3 or
> copies from dolfin/doc/.../.rst and generates its own html.
> 

The above is a good reason to get the doc building for each project
working - it's hard to think too many steps ahead.

Garth


> -- 
> Marie
> 
>>
>> 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
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp