Separate C++ and Python DOLFIN Sphinx projects
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
Related bugs
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.fenicsproje
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.