Separate C++ and Python DOLFIN Sphinx projects

Registered by Marie Rognes

Suggest having separate sphinx projects for the DOLFIN C++ and Python documentation (and for each version). With such a setup, the generated index will be way more clear and more easily navigated. The C++ project should include the generated API and the demos (so that the demos can link to the API), while the Python project should include the generated API, the demos and the tutorial (so that the demos and the tutorial can link to the API).

Blueprint information

Status:
Complete
Approver:
None
Priority:
Undefined
Drafter:
None
Direction:
Needs approval
Assignee:
Marie Rognes
Definition:
New
Series goal:
None
Implementation:
Implemented
Milestone target:
None
Started by
Marie Rognes
Completed by
Marie Rognes

Related branches

Sprints

Whiteboard

You can already link to the different APIs using 'domains' in Sphinx :cpp:class:`Mesh` and :py:class:`Mesh`. I think the index is already split in a C++ and Python version, and only the common text (like equations and problem definition) is shared in each demo while any language specific implementation is in separate files. This is in good agreement with the desire of avoiding redundant text which has to be updated.

MER: I'm thinking of the sphinx generated "Index" (generated by default in genindex.html) for the API. Absolutely agree that demos should share common text.

KBO: I don't see any links to genindex.html (or the module index, Python) anyway, but it makes sense to have different projects for different versions such that Array doesn't point to 10 different versions.

MER: At the moment (at www.fenicsproject.org), there are no links to genindex.html... I think there should be, and moreover, I think this should be the main link for the API documentation. I use the index as the main point of entry for virtually everything. The documentation web page for a given version could contain links to Programmer's Reference (C++) (the generated genindex.html), Programmer's Reference (Python) (again a (different) generated genindex.html if these are separate sphinx projects), to the demos (C++) and to the demos (Python). That way everything would look clean and be within easy access with only few (around two) clicks.

KBO: I see that it's quite annoying to have C++ and Python mixed up in the index, if you use the index a lot and find it useful, then others might be of the same opinion. I just look at the source files, so I don't have a really strong feeling in the matter. Let's try to split the programmer's reference according to language and versions and link to these from the main fenics-doc.

MER: Ok, good. Unless anyone else objects vehemently, I'll set something like this up for the web/doc (when I get around to it).

MER: I'll claim this is done. Open new blueprints for related issues.

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.