-
Notifications
You must be signed in to change notification settings - Fork 184
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update how_to_docs as per recent changes #720
Changes from 5 commits
85af878
16270ca
2d6b4e3
210a3e8
c5542ee
94d0f1f
3e9e723
8d00035
6ec6f5a
7c4f583
c81d4cf
2c32859
8b93823
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -39,16 +39,23 @@ Please, if you have problems with the documentation create an issue and let us k | |
Compile the documentation locally | ||
---------------------------------- | ||
|
||
To create the documentation locally, you need sphinx. It may be installed using specification | ||
form `doc/environment.docs.yaml` like is was done when creating `pypsa-earth` environment: | ||
To create the documentation locally, you need `Sphinx <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ . It can be installed using specifications | ||
form `doc/requirements.txt`. First, we recommend creating a fresh python environment and activate it: | ||
|
||
.. code:: bash | ||
|
||
.../pypsa-earth % mamba env create -f envs/environment.docs.yaml | ||
.../pypsa-earth % conda create --name pypsa-earth-docs python | ||
|
||
.../pypsa-earth % conda activate pypsa-earth-docs | ||
.../pypsa-earth % conda activate pypsa-earth-docs | ||
|
||
Then the following commands allow you to create the documentation locally: | ||
Next, install the packages specified in `doc/requiremnts.txt` using `pip`: | ||
|
||
.. code:: bash | ||
|
||
.../pypsa-earth % pip install -r doc/requirements.txt | ||
|
||
|
||
Once installation is completed, the following commands allow you to create the documentation locally: | ||
|
||
.. code:: bash | ||
|
||
|
@@ -58,3 +65,8 @@ Then the following commands allow you to create the documentation locally: | |
|
||
This will create html files in `pypsa-earth/doc/_build/html`. | ||
VScode provides a so called Liveserver extension such that the html file can be opened locally on your computer. | ||
|
||
.. note:: | ||
To build the documentation, Windows users might need to replace the last command by: | ||
|
||
.../pypsa-earth/doc (pypsa-earth-docs) % ./make html | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks a lot for thinking about platform specific details. It will be definitely very helpful Just a double-check question: should it be really "./", not "." which is a usual path separator in Windows? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hi @ekatef, good point. I summarise my findings below: After inspection, the original instruction The command Since the original command There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @asolavi, thanks a lot for the investigation. My feeling is that your findings may be a good support to get starting with sphinx. It seems from this SO discussion that the issues you experienced are quite common. As an idea, I'd suggest to keep the note changing its content to something more general. For example:
Although, I'm not sure if such an instruction would be really meaningful and absolutely do not insist on it. Feel free to disagree :) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks @ekatef, the SO link you provided is really helpful and I have added your suggestions with minor adjustments. The intention is to keep it as a list in case other similar issues arise in the future, which could be added to the list. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looks great, I think. Nice idea with a list to-be-continued :) |
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think between line 69 and 70 you need a empty line
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thank you, done.