We plan to create a user guide for our software project. Currently, everything related to the code is described in Sphinx, and we would like to use Sphinx for guidance.
As we write scientific / engineering software, there will be many topics such as stress, deformation, numerical algorithms, etc. For each topic, we will have several stages of information:
- Basic Information: This one or two descriptions of the proposal can be used wherever we need a short summary of the topic. Example: a simple definition of mechanical stress.
- A more detailed description: An explanation of this paragraph can be used as opening a help page or resume in a more detailed list of topics. Example, paragraph on mechanical stress introducing an equation for axial stress.
- Technical information. This may be a few paragraphs about how the topic relates to the problems that users of our software face.
- Information about the codes. This will be the documentation related to where this topic appears in the code. For example, we can point to our implementation of a specific numerical algorithm. We can use sphinx-apidoc as it is currently.
As you can see, information is gradually becoming more complex. We would like to manage each topic in our own .rst file and get the necessary information as needed. For example, perhaps we want to use the basic information section in a tooltip. In the help menu, we can use the detailed description in the table of contents for a particular class of topics. In a full article on this topic, for example, about what will be present in the full pdf-manual, we can provide technical information along with basic and more detailed descriptions. Finally, we would like to save code information only in our internal documentation.
It would be nice to save all the information for one topic in a single file, but conditionally compile different sections based on the documentation created.
- Sphinx? - - , ?