Closed Bachibouzouk closed 3 years ago
Nice, this looks much better @Bachibouzouk!
Some remarks:
Getting Started
, Examples
, etc. are leaning towards the previous section, not the following one. Can that be changed?
Getting Started/Introduction
. Is that because it does not really exist, or is that because it is the start page?Examples
? Maybe Getting Started/Simulating with the MVS/Defining an energy system
is already an example? Not sure.benchmark tests
to Examples
but leave them in Model Reference/Validation methodology
? I completely agree, I also like them there better. 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.Model Reference/Input parameters/
The Table of parameters
follows the List of parameters
. I think they should switch places.Model Reference/constraints
seperately. One would want to jump there quickly.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"?I only checked the vizuals for now. Maybe @ciaradunks can check the commits?
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 ;)
- 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 startIt 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
? MaybeGetting 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
toExamples
but leave them inModel 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 intoModel 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.
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?
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")
)
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?
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
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?
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
Weirdly enough, the changes of this pull request are not online yet:
They are in the build of #857 (here, PDF compilation also works):
It is not wierd, it is because I am fixing it in this branch :)
The last build on dev failed
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
The following steps were realized, as well (if applies):
black . --exclude docs/
)EXECUTE_TESTS_ON=master pytest
)For more information on how to contribute check the CONTRIBUTING.md.