Revise docs

[MaGering]

The docs are partly outdated and need to be revised.

1. Parts that need revisions must be identified
2. Missing info must be added

Open docs issues:

• [docs] Readme file is not nice #3 (Milestone v0.01)
• oemof-B3 process should be explained in more detail in docs #81 (No milestone set yet)

[MaGering]

Tasks can be collected here

(jnnr): @monika-o please do another review of the docs to find out the parts that need to be adressed before the release.

1. Parts that need revision:

   • Mention in Getting started that python<=3.8 is required
   • (v0.0.2) Update description in Examples: Give an instruction on how to run the examples avoiding duplication with Getting started. Add there a link to here. - solution in PR Revise docs #119
   • (v0.0.2) Getting started: Instead of how to run on Linux / windows: how to run the model and add snakemake -j... how to run the model - solution in PR Revise docs #119
   • Q: Isn't required data provided now in the examples? Getting started says the opposite. A: The examples can be run, but required data for scenarios is not published.
   • (v0.01) Adapt variables under Elements in Model Structure to the ones appearing in schema
     • How is schema/scalars.csv and the actual files under .../data/elements technically and content-wise connected? The structure does not appear to be the same, e.g. the scenario is not mentioned in the actual file.
     • What is the difference between "oemof-B3 resources" and "Preprocessed datapackages"?
       • Where are the units specified?
       • region: Where are the regions specified? The mentioned file /oemof_b3/model/topology.yml apparently doesn't exist
       • carrier: Explain the difference between carrier and bus.
   • (v0.01) Revise Model pipeline
     • General: What is the model pipeline? Which of these scripts are automatically executed when running snakemake -j<NUMBER_OF_CPU_CORES> run_all_examples and how can I find that out?
     • (v0.0.2) build_datapackage - solution in PR Revise docs #119
       • What does an EnergyDatapackage look like?
       • Where is it stored by default when running snakemake -j<NUMBER_OF_CPU_CORES> plot_all_examples?
     • (v0.0.2) build_datapackage: No content - solution in PR Revise docs #119
     • (v0.0.2) create_input_data_overview: No content - solution in PR Revise docs #119
     • (v0.0.2) prepare_heat_demand: No content - solution in PR Revise docs #119
     • (v0.0.2) prepare_vehicle_charging_demand: No content - solution in PR Revise docs #119
     • postprocess: A more meaningful description would be helpful - solution in PR Revise docs #119
     • Plotting: No content yet. Explain how to generate the plot that is currently already in the dev branch.
   • The introductory paragraph to the model structure is very hard to grasp for people who are unfamiliar with oemof.
   • Where and what is the TYPEMAP? (model structure)
   • Show some docs under API

2. Info to be added:

   • (v0.0.3) Provide more information about the input data
     • How can a maximum capacity be implemented? If there is only a single capacity value, what does it mean?
     • Which structure must the time series input data have?
     • Where should the input data be stored other than in the examples folder?
   • How can a different scenario be generated? Which files need to be changed and how?
     • How can a user run a scenario other than the three examples with snakemake?
   • Mention the timeframe somewhere - does it have to be a year?
   • Postprocessed data should be documented referencing to oemoflex's documentation: Cf. issue Postprocessed data is not documented oemoflex#54 - solution in PR Revise docs #119
   • (v0.0.3) Revise "Required data" as soon as raw data is provided in oemof-B3
   • (v0.0.3) Add info about the clean rule: Executing snakemake -j1 clean you can clean all calculated scenarios in the directory results.
   • (v0.0.3) Add info about snakemake -j1 create_empty_scalars and snakemake -j1 create_empty_ts in a new paragraph under "Contributing to oemof-B3": Developing new scenarios. It should say something like this: "If you're developing new scenarios or calculations based on oemof-B3 you may need to change the model structure of your energy system by for instance adding components. You can create new empty scalar and time series data for this modified energy system using..."

3. Technical issues:

   • There seems to be a problem with building the docs, because the list about snakemake in Getting started is not printed as a list, but it is when I build it locally. DONE on fix/rtd_theme
   • I would remove the contents section in the beginning of each page because it is redundant with the side panel.
   • (v0.0.2) Links in "getting started" are not rendered - no correct rtf syntax.

4. To be defined in oemof.tabular or oemoflex

   • (v0.0.3) How can a scenario be made expandable? Simply by setting expandable to true in the elements input data?

5. handle open documentation issues

   • (v0.0.2) Apply changes proposed in issue oemof-B3 process should be explained in more detail in docs #81 and comment Feature/improve docs #263 (comment).
   • issue Warnings of duplicate label inputs while building docs #179

[monika-o]

The above list has got quite extensive. In my opinion, the most important tasks are the revision of the model pipeline, simply because it looks very incomplete, and a documentation of what @SabineHaas wrote in #81.
I have created a new branch to work on the docs: features/update-docs.

[MaGering]

Some docstrings are not rendered with automodule in Model pipeline. @jnnr can you help with this?

[jnnr]

To give a better intro into the model pipeline, we can add a graphic of the DAG, like this

[MaGering]

• (v0.0.2) Links in "getting started" are not rendered - no correct rtf syntax.

@monika-o , @jnnr: Do any of you know what is meant by this? I don't see any links that are not rendered. I would otherwise remove this item from the ckeckbox list.

[monika-o]

There are two links in the installation section where the text that should clickable as link is displayed in square brackets and the actual link (which should be hidden) follows in normal brackets. This concerns pandoc installation and oemof.solph.

[MaGering]

There are two links in the installation section where the text that should clickable as link is displayed in square brackets and the actual link (which should be hidden) follows in normal brackets. This concerns pandoc installation and oemof.solph.

Thanks for specifying @monika-o. Looks like this was supposed to be a feature and not a bug ;-) However, I fixed this with commit 506d180 in PR #263.

[monika-o]

Time has passed and I have a few new comments:
[issue written (#318) ] The windows issue with snakemake is closed now, but in the docs it says that it's open. I don't know whether the problem itself has been solved.
[x] Are the first full scenario now available? (In overview we say that they will be made available in the coming months)
[x] upload_b3_data_to_oep is empty.

[MaGering]

Thanks for looking into it @monika-o

[ ] The windows issue with snakemake is closed now, but in the docs it says that it's open. I don't know whether the problem itself has been solved.

Could you write an issue for this? It has to be checked if the snakemake execution works with windows by now.

[ ] Are the first full scenario now available? (In overview we say that they will be made available in the coming months)

Thanks I took it out.

[ ] upload_b3_data_to_oep is empty.

I fixed this with commit 13ea89f. However download_resources.py needs a docstring, that can be displayed in the model pipeline (I just added download_resources there because it was missing). Could you write an issue for this too?

[MaGering]

[ ] (v0.0.3) Provide more information about the input data

* [ ]  How can a maximum capacity be implemented? If there is only a single capacity value, what does it mean?

@Stefanie08 I think we've already looked at this but could you check if we have this ↑ covered? Basic message should be:

• Already installed capacity is provided with the attribute capacity (e.g. 0 if Greenfield and other positive numeric value if Brownfield)
• A maximum capacity is set with a positive numeric value for the attribute capacity_potential. An empty capacity_potential corresponds to an infinite capacity potential.

Actually, this should be documented in oemof.facades. But maybe you can find it in oemoflex or here in this repo. I would plead for it to be added here in the repo if it is not documented in the other two, to at least have it somewhere. You can use #327 for this. Thanks! :)

[MaGering]

• I would remove the contents section in the beginning of each page because it is redundant with the side panel.

Could you do this in PR #327 as well @Stefanie08? I think it should not take too much time. Thank you!

[Stefanie08]

The contents section is removed with commit 88548e1.
The description for the maximum capacity and the already installed capacity is done with commit e1a67d1.