Improve doc

[martavp]

At AU, we have been working on improving the documentation.

We are still missing a few tasks before this PR is ready to be reviewed, but @Parisra, @Adam-Dvorak1 and @ebbekyhl will take care of them next week

TODOs LIST

[x] Add internal links from some sections to others

[x] Harmonize style in title and subtitle

[x] Review the description of the myopic approach and describe better carbon budget

[x] Finish and review Other industrial sectors

[x] Add description of energy consumption in agriculture

[ ] Create an overview of the rules like in PyPSA-Eur (maybe this can be done in a future step)

[martavp]

We are finally ready for this PR to be reviewed. I have suggested @energyLS, @lisazeyen and @fneum as reviewers.

This PR will conflict with https://github.com/PyPSA/pypsa-eur-sec/pull/264 because we have included many references to specific lines in the config file that would need to be updated once https://github.com/PyPSA/pypsa-eur-sec/pull/264 is merged.

[fneum]

Great, thanks @martavp! We'll prioritise this PR over #264.

[fneum]

Current build for this PR: https://pypsa-eur-sec.readthedocs.io/en/martavp-improve-doc/

[fneum]

Thanks @martavp et al. for preparing this documentation boost, and thanks @energyLS for kicking of the review. One issue I saw in the preview (https://pypsa-eur-sec.readthedocs.io/en/martavp-improve-doc/) is that the equations are not properly resolved. I.e. in RST syntax, math mode needs to be activated not with $$ ... $$ but with

.. math::
   \frac{ \sum_{t=0}^{N}f(t,k) }{N}

or inline

:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`

[martavp]

Thanks for the initial revision @energyLS

[martavp]

Thanks @martavp et al. for preparing this documentation boost, and thanks @energyLS for kicking of the review. One issue I saw in the preview (https://pypsa-eur-sec.readthedocs.io/en/martavp-improve-doc/) is that the equations are not properly resolved. I.e. in RST syntax, math mode needs to be activated not with $$ ... $$ but with

.. math::
   \frac{ \sum_{t=0}^{N}f(t,k) }{N}

or inline

:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`

We implemented the correct math notation here: https://github.com/PyPSA/pypsa-eur-sec/pull/265/commits/bf37fcc27562af10fef9327b618ffaa9a563b483

[fneum]

Great! Thanks for all your work! The references to lines in the config.yaml will be hard to maintain, but we can find a solution separately from this PR.

[martavp]

Finished the review of supply_demand.rst. Great effort, detailed descriptions, well readable. The suggestions are mainly typos. The cross-referencing to subsections seems not to work, please doublecheck. The industry section was tiring to read since it is very detailed, but that's adequate and how it should be :)

thanks for the review, @energyLS Yes, industry always super long to describe :)

[martavp]

Great! Thanks for all your work! The references to lines in the config.yaml will be hard to maintain, but we can find a solution separately from this PR.

Sure, we can find other ways to do it. I think it always clarifies to have a direct link between the documentation and where to change a particular assumption.