-
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
Conversation
@ekatef shall we change the default checklist of a PR too? Point 4 states "Newly introduced dependencies are added to I don't know how to change these settings. |
Fantastic @asolavi! Very clear and nice explanations. The checklist for PRs is a part of |
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.
Looks good. Please only change the little comments from me and Katia and this is ready to merge 🎉 👍
doc/how_to_docs.rst
Outdated
@@ -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: |
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.
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.
doc/how_to_docs.rst
Outdated
|
||
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 comment
The 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?
Could you also explain a bit on why does this fix help?
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.
Hi @ekatef, good point. I summarise my findings below:
After inspection, the original instruction make html
now works well on the PowerShell of my Windows laptop. This was not the case in the past (that is why I looked for the ./make html
workaround). Some PowerShell configuration might have changed during this time that fixed it, but I can't tell what it is.
The command .make html
does not work on my windows laptop. I get this error: make_error.txt.
Since the original command make html
seems to be working fine, shall we remove the Note box?
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.
@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:
- Windows users can face some problems when trying to build docs locally depending on an OS version and terminal used;
- a workaround definitely can be found;
- we can suggest to look for a solution on SO (or something alike).
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 comment
The 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 comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great, I think. Nice idea with a list to-be-continued :)
Thanks a lot @asolavi! Great work :) Could you please address a comment related to a workflow on Windows? That is amazing that you have some hints there. My general impression is that it may be quite a challenge to get the workflow run on Windows. So, any recommendations there are highly important |
for more information, see https://pre-commit.ci
Thank you @ekatef, I've introduced your suggestions. What do you think? |
@asolavi great work! Thanks a lot for the contribution 🙂 |
Thanks for your feedback and constant support, @ekatef ! :) |
Introduction
Update instructions on
doc/how_to_docs.rst
. This is required given recent updates on how the documentation is compiled. It arised as a follow-up discussion from PR #694.Changes proposed in this Pull Request
pypsa-earth/envs/environment.docs.yaml
.doc/how_to_docs.rst
to match the new method manually creating the environment.See #694 (comment) for further reference.
Checklist
envs/environment.yaml
andenvs/environment.docs.yaml
.config.default.yaml
andconfig.tutorial.yaml
.test/
(note tests are changing the config.tutorial.yaml)doc/configtables/*.csv
and line references are adjusted indoc/configuration.rst
anddoc/tutorial.rst
.doc/release_notes.rst
is amended in the format of previous release notes, including reference to the requested PR.