Restructure readthedocs

[Bachibouzouk]

Addresses part of #764
Addresses part of #849

Changes proposed in this pull request:
The index of the RTD should be changed to this structure

Multi-vector simulator
================

Project description

Maintainers
===========

Say who develop and maintains this

Say a word about funding

Origin
======

What started MVS

.. Documentation
.. =============

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Getting Started

   introduction
   installation
   (link to troubleshooting for report)
   Simulating with MVS

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Examples

Adding a timeseries for a parameter (now in Simulating with the MVS/Defining an energy system)
Using multiple in or output busses (now in Simulating with the MVS/Defining an energy system)
Benchmark tests


.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Model Reference

   Assumptions & Equations merged together
      Energy carriers possible from one source
   Limitations

   Input Parameters (rst inside the root and subchapter as rst inside a folder)
     Parameters in each category/CSV file
     Parameters table (shrinked or link to expanded standalone page)
     List of parameters
   Output Parameters
   	
   	Output KPI (how we calculate them)
   	   Short description loaded automatically form .inc files generated form a MVS_outputs.csv
   	       Columns :Definition:,valid_interval,:Type:,:Unit:,label,ref,categories (economic, technical, environemental? --> technical),see_also (collection of links)
   	   Not in a csv file for the complete and formal mathematical definition
   	Output suffixes
  	   Explain the logic of the suffixes for the output parameters
   	output files
	    network
	    png
   	    report
   	
   Validation
   E-Land requirements of the MVS (or delete them from dev but keep them in branch report to H2020)
   

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: References

   ref_api (Currently code documentation) (for website, move to end for report)
   release_notes (for website, remove for report, not implemented yet, nice to have)
   contributing (here paste content of contributing.md --> convert to RST and include it as we did for readme, the mention to contributing in getting started will link to this chapter)
   license
   Publications
   Cite MVS
   Troubleshooting 
   Reporting bugs 

The following steps were realized, as well (if applies):

• Use in-line comments to explain your code
• Write docstrings to your code (example docstring)
• For new functionalities: Explain in readthedocs
• Write test(s) for your new patch of code (pytests, assertion debug messages)
• Update the CHANGELOG.md
• Apply black (black . --exclude docs/)
• Check if benchmark tests pass locally (EXECUTE_TESTS_ON=master pytest)

_{For more information on how to contribute check the CONTRIBUTING.md.}

[smartie2076]

Nice, this looks much better @Bachibouzouk!

Some remarks:

• The indents of the sections Getting Started, Examples, etc. are leaning towards the previous section, not the following one. Can that be changed?
  
• There is no specific Getting Started/Introduction. Is that because it does not really exist, or is that because it is the start page?
• Can you add a blanko file for an energy system example below Examples? Maybe Getting Started/Simulating with the MVS/Defining an energy system is already an example? Not sure.
• Did you explicitly decide to not move the benchmark tests to Examples but leave them in Model Reference/Validation methodology? I completely agree, I also like them there better.
• For me, Component models also belongs into Model reference/Assumptions - because the model representations are also assumptions of a kind. At the same time, they are also explaining how the MVS can be used and how certain assets are to be defined... Maybe we just need to shift some things around here.
• In Model Reference/Input parameters/ The Table of parameters follows the List of parameters. I think they should switch places.
• I agree with having Model Reference/constraints seperately. One would want to jump there quickly.
• For me, having the References/Code documentation so far up there is quite dominant - I would probably move them to the end ot the section. Didnt you say it has to be called "API documentation"?

[smartie2076]

I only checked the vizuals for now. Maybe @ciaradunks can check the commits?

[Bachibouzouk]

Nice, this looks much better @Bachibouzouk!

Some remarks:

* The indents of the sections `Getting Started`, `Examples`, etc. are leaning towards the previous section, not the following one. Can that be changed?
  ![grafik](https://user-images.githubusercontent.com/44204527/114046271-ffd42700-9888-11eb-8040-cf056add4aa1.png)

It can certainly be changed, locally it displays like this:

* There is no specific `Getting Started/Introduction`. Is that because it does not really exist, or is that because it is the start page?

It is the start page, that is how it was in atlite docs, but I find a bit weird that one cannot see this menu on the side to come back to it

* Can you add a blanko file for an energy system example below `Examples`? Maybe `Getting Started/Simulating with the MVS/Defining an energy system` is already an example? Not sure.

A new section? or a new item into Example ? Getting Started/Simulating with the MVS/Defining an energy system is not an example as it is general, an example would provide as file to be able to reproduce the system provided in the example and explain step by step.

* Did you explicitly decide to not move the `benchmark tests` to `Examples` but leave them in `Model Reference/Validation methodology`? I completely agree, I also like them there better.

As they are they belong to Model Validation, we could turn one or two of the benchmark tests into examples with highlight of the parameters the user has to pay attention to, just having the file forces the user to figure it alone.

* For me, `Component models` also belongs into `Model reference/Assumptions` - because the model representations are also assumptions of a kind. At the same time, they are also explaining how the MVS can be used and how certain assets are to be defined... Maybe we just need to shift some things around here.

I wanted to get a little bit of things out of Assumptions and Components one is able to model is something a potential user would be interested in. We could also look at the docs of https://pypsa.readthedocs.io/en/latest/index.html for inspiration.

* In `Model Reference/Input parameters/` The `Table of parameters` follows the `List of parameters`. I think they should switch places.

This is easy fix

* I agree with having `Model Reference/constraints` seperately. One would want to jump there quickly.

* For me, having the `References/Code documentation` so far up there is quite dominant - I would probably move them to the end ot the section. Didnt you say it has to be called "API documentation"?

This is the place for the website, in the structure draft above I mention that for the report, this will be moved downwards ;)

[smartie2076]

• The indents of the sections Getting Started, Examples, etc. are leaning towards the previous section, not the following one. Can that be changed?

It can certainly be changed, locally it displays like this:

Weird, maybe that is just because it is a preliminary compilation?

• There is no specific Getting Started/Introduction. Is that because it does not really exist, or is that because it is the start

It is the start page, that is how it was in atlite docs, but I find a bit weird that one cannot see this menu on the side to come back to it

I agree, it is not 100% clear

• Can you add a blanko file for an energy system example below Examples? Maybe Getting Started/Simulating with the MVS/Defining an energy system is already an example? Not sure.

A new section? or a new item into Example ? Getting Started/Simulating with the MVS/Defining an energy system is not an example as it is general, an example would provide as file to be able to reproduce the system provided in the example and explain step by step.

New item, but really, we can also do that later when we actually write it.

• Did you explicitly decide to not move the benchmark tests to Examples but leave them in Model Reference/Validation methodology? I completely agree, I also like them there better.

As they are they belong to Model Validation, we could turn one or two of the benchmark tests into examples with highlight of the parameters the user has to pay attention to, just having the file forces the user to figure it alone.

Yeah, we can explain them in more detail and adapt one to be an "EXAMPLE" in a later PR.

• For me, Component models also belongs into Model reference/Assumptions - because the model representations are also assumptions of a kind. At the same time, they are also explaining how the MVS can be used and how certain assets are to be defined... Maybe we just need to shift some things around here.

I wanted to get a little bit of things out of Assumptions and Components one is able to model is something a potential user would be interested in. We could also look at the docs of https://pypsa.readthedocs.io/en/latest/index.html for inspiration.

I see and agree with having them seperate. I think that creating a better structure is something that will happen when proof-reading existing text.

[ciaradunks]

Hey @Bachibouzouk, I've looked through the commits so far and they all look fine (no files changed that shouldn't have been). I'm trying to build the readthedocs locally to see how it looks, but am getting the following error:

Are you getting this as well?

[Bachibouzouk]

Hey @Bachibouzouk, I've looked through the commits so far and they all look fine (no files changed that shouldn't have been). I'm trying to build the readthedocs locally to see how it looks, but am getting the following error:

@ciaradunks - No I don't

This seems to be happening in the file reading process (when I copy readme into the RTD) in conf.py, basically I want to read the file, get rid of the README intro and keep only from setup. This seems not to work on windows... can you try to specifiy the encoding where the file is opened ( something like file = open(filename, encoding="utf8"))

[smartie2076]

Nice! Now we can start improving it :D

[ciaradunks]

I've seen that in the table of parameters it says that the unit, type and example values will be shown, but the type unit and default values are atually shown. Now this is merged though I can make a small issue or PR?

[Bachibouzouk]

Now this is merged though I can make a small issue or PR?

You can, but example will make the width of the table too large to fit, this is why I changed it to Default

[smartie2076]

We anyway have do proof-read still, and we can adress this content-related issues when we do. This PR should not produce a finished RTD, but only the correct structure. @Bachibouzouk should we rather create an issue where we list all the RTD shortcomings, or is it better to create a lot of small PR?

[Bachibouzouk]

I would do one large PR for fixing external links (see #856), one for fixing warnings and then small PR focusing on a restricted number of .rst files

[smartie2076]

Weirdly enough, the changes of this pull request are not online yet:

They are in the build of #857 (here, PDF compilation also works):

[Bachibouzouk]

It is not wierd, it is because I am fixing it in this branch :)

[Bachibouzouk]

The last build on dev failed