Update how_to_docs as per recent changes #720

asolavi · 2023-05-08T12:53:47Z

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

Remove pypsa-earth/envs/environment.docs.yaml.
Update instructions on doc/how_to_docs.rst to match the new method manually creating the environment.

See #694 (comment) for further reference.

Checklist

I consent to the release of this PR's code under the GPLv3 license and non-code contributions under CC0-1.0 and CC-BY-4.0.
I tested my contribution locally and it seems to work fine.
Code and workflow changes are sufficiently documented.
Newly introduced dependencies are added to envs/environment.yaml and envs/environment.docs.yaml.
Changes in configuration options are added in all of config.default.yaml and config.tutorial.yaml.
Add a test config or line additions to test/ (note tests are changing the config.tutorial.yaml)
Changes in configuration options are also documented in doc/configtables/*.csv and line references are adjusted in doc/configuration.rst and doc/tutorial.rst.
A note for the release notes doc/release_notes.rst is amended in the format of previous release notes, including reference to the requested PR.

for more information, see https://pre-commit.ci

asolavi · 2023-05-08T13:48:50Z

@ekatef shall we change the default checklist of a PR too? Point 4 states "Newly introduced dependencies are added to envs/environment.yaml and envs/environment.docs.yaml.", but envs/environment.docs.yaml does not exist anymore.

I don't know how to change these settings.

…arth into doc_instructions

ekatef · 2023-05-08T17:35:00Z

Fantastic @asolavi! Very clear and nice explanations.

The checklist for PRs is a part of pull_request_template.md placed in pypsa-earth/.github folder

pz-max

Looks good. Please only change the little comments from me and Katia and this is ready to merge 🎉 👍

pz-max · 2023-05-08T21:49:10Z

doc/how_to_docs.rst

@@ -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:


I think between line 69 and 70 you need a empty line

thank you, done.

asolavi · 2023-05-09T09:17:01Z

Thank you @ekatef and @pz-max for your help and feedback. The two comments have been addressed, and therefore ready to merge :).

pz-max

Looks good. Thanks @asolavi 🥇
Waiting for @ekatef review and her merge

ekatef · 2023-05-09T22:35:56Z

doc/how_to_docs.rst

+
+    To build the documentation, Windows users might need to replace the last command by:
+
+        .../pypsa-earth/doc (pypsa-earth-docs) % ./make html


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?

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?

@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 :)

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.

Looks great, I think. Nice idea with a list to-be-continued :)

ekatef · 2023-05-09T22:44:17Z

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

asolavi · 2023-05-12T14:55:53Z

Thank you @ekatef, I've introduced your suggestions. What do you think?

ekatef · 2023-05-12T21:54:25Z

@asolavi great work! Thanks a lot for the contribution 🙂

asolavi · 2023-05-15T14:53:57Z

Thanks for your feedback and constant support, @ekatef ! :)

ekatef · 2023-05-16T09:58:51Z

Thanks for your feedback and constant support, @ekatef ! :)

@asolavi My pleasure and happy to continue :)

Remove environment.docs.yaml

85af878

asolavi mentioned this pull request May 8, 2023

Documentation improvement in the configuration section_v2 #694

Merged

8 tasks

asolavi and others added 2 commits May 8, 2023 14:45

Update instructions to install documentation environment.

16270ca

[pre-commit.ci] auto fixes from pre-commit.com hooks

2d6b4e3

for more information, see https://pre-commit.ci

asolavi added 2 commits May 8, 2023 14:51

Add release note for the PR.

210a3e8

Merge branch 'doc_instructions' of https://github.com/asolavi/pypsa-e…

c5542ee

…arth into doc_instructions

pz-max requested changes May 8, 2023

View reviewed changes

asolavi added 2 commits May 9, 2023 10:14

Fix typo in how_to_docs.rst

94d0f1f

Update reference to doc environment in PR request template.

3e9e723

asolavi and others added 4 commits May 9, 2023 10:25

Resolve merge conflicts in release_notes.rst

8d00035

Resolve merge conflicts v2

6ec6f5a

Merge branch 'pypsa-meets-earth:main' into doc_instructions

7c4f583

Update release_notes after merging conflicts have been resolved.

c81d4cf

pz-max marked this pull request as ready for review May 9, 2023 11:39

pz-max approved these changes May 9, 2023

View reviewed changes

pz-max requested a review from ekatef May 9, 2023 11:41

ekatef reviewed May 9, 2023

View reviewed changes

asolavi and others added 2 commits May 12, 2023 15:54

Improve note on windows users.

2c32859

[pre-commit.ci] auto fixes from pre-commit.com hooks

8b93823

for more information, see https://pre-commit.ci

ekatef merged commit 22d2a45 into pypsa-meets-earth:main May 12, 2023

asolavi deleted the doc_instructions branch May 15, 2023 14:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update how_to_docs as per recent changes #720

Update how_to_docs as per recent changes #720

asolavi commented May 8, 2023 •

edited

Loading

asolavi commented May 8, 2023

ekatef commented May 8, 2023

pz-max left a comment

pz-max May 8, 2023

asolavi May 9, 2023

asolavi commented May 9, 2023

pz-max left a comment •

edited

Loading

ekatef May 9, 2023

asolavi May 10, 2023 •

edited

Loading

ekatef May 10, 2023 •

edited

Loading

asolavi May 12, 2023

ekatef May 12, 2023

ekatef commented May 9, 2023

asolavi commented May 12, 2023

ekatef commented May 12, 2023

asolavi commented May 15, 2023

ekatef commented May 16, 2023


		To build the documentation, Windows users might need to replace the last command by:

		.../pypsa-earth/doc (pypsa-earth-docs) % ./make html

Update how_to_docs as per recent changes #720

Update how_to_docs as per recent changes #720

Conversation

asolavi commented May 8, 2023 • edited Loading

Introduction

Changes proposed in this Pull Request

Checklist

asolavi commented May 8, 2023

ekatef commented May 8, 2023

pz-max left a comment

Choose a reason for hiding this comment

pz-max May 8, 2023

Choose a reason for hiding this comment

asolavi May 9, 2023

Choose a reason for hiding this comment

asolavi commented May 9, 2023

pz-max left a comment • edited Loading

Choose a reason for hiding this comment

ekatef May 9, 2023

Choose a reason for hiding this comment

asolavi May 10, 2023 • edited Loading

Choose a reason for hiding this comment

ekatef May 10, 2023 • edited Loading

Choose a reason for hiding this comment

asolavi May 12, 2023

Choose a reason for hiding this comment

ekatef May 12, 2023

Choose a reason for hiding this comment

ekatef commented May 9, 2023

asolavi commented May 12, 2023

ekatef commented May 12, 2023

asolavi commented May 15, 2023

ekatef commented May 16, 2023

asolavi commented May 8, 2023 •

edited

Loading

pz-max left a comment •

edited

Loading

asolavi May 10, 2023 •

edited

Loading

ekatef May 10, 2023 •

edited

Loading