Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Update how_to_docs as per recent changes #720

Merged
merged 13 commits into from
May 12, 2023
Merged

Update how_to_docs as per recent changes #720

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
85af878
Remove environment.docs.yaml
asolavi May 8, 2023
16270ca
Update instructions to install documentation environment.
asolavi May 8, 2023
2d6b4e3
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] May 8, 2023
210a3e8
Add release note for the PR.
asolavi May 8, 2023
c5542ee
Merge branch 'doc_instructions' of https://github.com/asolavi/pypsa-e…
asolavi May 8, 2023
94d0f1f
Fix typo in how_to_docs.rst
asolavi May 9, 2023
3e9e723
Update reference to doc environment in PR request template.
asolavi May 9, 2023
8d00035
Resolve merge conflicts in release_notes.rst
asolavi May 9, 2023
6ec6f5a
Resolve merge conflicts v2
asolavi May 9, 2023
7c4f583
Merge branch 'pypsa-meets-earth:main' into doc_instructions
asolavi May 9, 2023
c81d4cf
Update release_notes after merging conflicts have been resolved.
asolavi May 9, 2023
2c32859
Improve note on windows users.
asolavi May 12, 2023
8b93823
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] May 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions doc/how_to_docs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Copy link
Member

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thank you, done.


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

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?

Copy link
Contributor Author

@asolavi asolavi May 10, 2023 •
edited
Loading

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?

Copy link
Collaborator

@ekatef ekatef May 10, 2023 •
edited
Loading

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:

  1. Windows users can face some problems when trying to build docs locally depending on an OS version and terminal used;
  2. a workaround definitely can be found;
  3. 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 :)

Copy link
Contributor Author

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.

Copy link
Collaborator

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

2 changes: 2 additions & 0 deletions doc/release_notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ PyPSA-Earth 0.2.0

* Improve earth coverage and add improve make_statistics coverage `PR #654 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/654>`__

* Update instructions on how to write documentation. `PR #720 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/720>`__

PyPSA-Earth 0.1.0
=================

Expand Down
74 changes: 0 additions & 74 deletions envs/environment.docs.yaml
View file
Open in desktop

This file was deleted.