Documentation overhaul

[tarskul]

There is a lot already there in the documentation but the flow of the document seems to be missing. Therefore, in this issue, we propose a new structure for the documentation. The endgoal is to make it easier for the user to find what they are looking for.

Part 1: Just do it!

A part of the current spirit of the SpineOpt project is to dive in first and deal with problems as you go. That is also reflected in the current version of the documentation where we get the instructions as to how to get started with SpineOpt. That is fine, so we keep that focus in the first part. The introduction should make clear what kind of model SpineOpt is and what kind of use cases there are. Additionally, it should be mentioned how it differs from other models. Off course, the introduction also has an overview of the documentation, including the explanation in this issue. Getting started used to contain an example. That example is going to be scrapped and the simple system tutorial is going to take its place. The tutorials will have unit tests so it will be easier to keep them up to date. The how to is considered as a bonus to give some additional information on how to get things done.

• Intro
• Intro
• Getting started
• Installation
• Recommended workflow
• Trouble shooting
• Tutorials
• How to

Part 2: Principles and design

The second part attempts to explain the core principles, features and design decisions in SpineOpt without getting lost in the details. What was originally available across 'concept reference' and 'advanced concepts' is now split and regrouped. The parts that remain in 'Principles and design' are the explanation about model, temporal structure, stochastic structure, unit, node, etc., the explanation about the main features that are covered by the mathematical formulation such as investment planning, ptdf, ... and the explanation of the different algorithms such as the main algorithm, Benders and MGA. The main features are organised according the time horizon (from long term to short term).

• SpineOpt's data driven model structure
• Overview
• Objects and relationships
• Temporal structure
• Stochastic structure
• Model features
• Overview
• Investment optimisation
• Unit commitment
• Ramping
• Reserves
• Lossless DC + PTDF
• User constraint
• Algorithms
• Overview
• Decomposition
• MGA

Part 3: Reference

All the detailed information you need when you are looking for something specific (e.g. a parameter name or the formulation of a constraint). It follows the same structure as the main features of the formulation. The parameters should also be ordered by the object and relationship classes instead of merely listing the parameters. The implementation details should follow the same structure as the remainder of the documentation.

• SpineOpt (spine) database structure
• Object classes
• Relationship classes
• Parameters + parameter value lists
• Mathematical formulation
• Variables
• Objective
• Constraints
• Implementation details
• Library

We suggest the following approach for implementing the documentation overhaul:

• [x] Agree on the proposed structure
• [x] Getting started
• [ ] tutorials: The progress of the tutorials are tracked in another issue (#735)
• [ ] rearrange pages for part 2
• [x] change doc_utils code to sort parameters by entities
• [ ] Do the same for objective and variables as for constraints
• [ ] Add missing documentation and clarify some parts
• [ ] Fix documentation warnings
• [ ] Make sure that no new warnings enter the documentation by setting warnonly to false (resolves issue #626)

[clizbe]

Maybe an interesting read before implementing this: https://diataxis.fr/

[jkiviluo]

I like this structure. Seems to be quite close to that diataxis too.