augmentation of documentation #71

fneum · 2019-05-24T19:06:45Z

@FabianHofmann and I discussed a few ideas for improving the PyPSA documentation:

add autodocs for documented functions
change theme to sphinx_rtd_theme from alabaster
readthedocs automatic deployment
remove some duplicate content
add shields.io stickers
API reference

What one could do another time:

update screenshots with new colors (fresh color palette for tech_colors pypsa-eur#35) and cartopy
sort examples

Current state is on https://pypsa-readthedocs.readthedocs.io/

Once merged, need to change settings on https://readthedocs.org and add correct webhook in github as well as forwarding https://pypsa.org/documentation to https://pypsa.readthedocs.io.

coroa · 2019-05-26T06:03:09Z

Is it possible to have an automatic read-the-docs deployment for this pull request only, for the time being?

FabianHofmann · 2019-05-26T16:26:49Z

we already worked on this during the openmod conference, and the commit already includes nice features. I think we can definitely comment out some of the changes (and keep it for later?). On the other hand, when introducing autodocs, you have to rewrite some of the text anyway to make it sensible. And then, you could/should go through the docs and watch out for redundant duplicates and sortings.
Is there a specific point you don't want to have included?

coroa · 2019-05-27T11:31:42Z

I think its good to have this PR to document the progress of the full checklist, but I would also like if the documentation is already updated now, so ideally someone would set up the service to auto-build based on the readthedocs branch instead of master.

fneum · 2019-05-27T12:25:54Z

https://pypsa-readthedocs.readthedocs.io/

coroa · 2019-05-28T11:10:52Z

Hi @fneum,

it'd be good to add [skip travis] to your doc-only commit messages as described in the travis docs, so we do not put unnecessary load on their servers.

Best,

fneum · 2019-05-28T11:58:02Z

Will do from the next commit onwards; forgot for the current one.

coroa · 2019-05-28T12:00:43Z

Great, let's use the style:

use sphinx.ext.napoleon for numpydocs [skip travis]

fneum · 2019-05-28T12:24:10Z

Current state is on https://pypsa-readthedocs.readthedocs.io/ and ready for review.

What one could do another time in separate pull requests:

update screenshots with new colors (fresh color palette for tech_colors pypsa-eur#35) and cartopy
sort/clean/update examples

I would recommend squashing the commits when merging.

coroa

I'm in general in favor with the updates. Having tighter links with the code probably helps deduplication.

Many packages split their documentation in a user guide and an API reference. Just compare with xarray or pandas. Perhaps that would make it a bit easier to find one's way around.

doc/import_export.rst

doc/plotting.rst

doc/power_flow.rst

environment_docs.yml

pypsa/component_attrs/networks.csv

pypsa/io.py

coroa

Great, I like the new menu arrangement! It's a lot less intimidating than it was before.

environment_docs.yml

pypsa/components.py

pypsa/io.py

doc/index.rst

coroa · 2019-05-29T11:49:31Z

While you're at it maybe add one of the conda-forge badges:

Name	Downloads	Version	Platforms

| Name | Downloads | Version | Platforms |
| --- | --- | --- | --- |
| [![Conda Recipe](https://img.shields.io/badge/recipe-pypsa-green.svg)](https://anaconda.org/conda-forge/pypsa) | [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/pypsa.svg)](https://anaconda.org/conda-forge/pypsa) | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pypsa.svg)](https://anaconda.org/conda-forge/pypsa) | [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/pypsa.svg)](https://anaconda.org/conda-forge/pypsa) |

I think, I'd take just the version one.

FabianHofmann · 2019-05-31T11:20:30Z

I added a small update on the plots in the introduction. it is minor changes in the docs but I had to update some parts in the scigrid and ac-dc-meshed scripts.

coroa · 2019-05-31T19:32:07Z

@FabianHofmann Thanks for the update of all these examples :), that was overdue.

Couple of comments:

You added a scigrid-lopf-then-pf.py script to the doc/img/ folder. I don't think that was intentional.
The Großkleinschreibung of Pypsa-EUR should be PyPSA-Eur.
The colors in the PyPSA-Eur plot are strange: Green for solar?? Probably best would be to use the tech_colors that @fneum prepared in fresh color palette for tech_colors pypsa-eur#35 .
The file sizes of the new plots are quite large, f.i. 1.2M for the PyPSA-Eur one. Less DPI or a bit smaller maybe (aim for ~ 400K or some such).

and

add the label [skip travis] to your commit messages to skip running tests for these doc updates.

coroa · 2019-06-03T07:58:49Z

Awesome! Thanks for the quick update addressing all my comments.

In as far as I am able to judge https://pypsa-readthedocs.readthedocs.io/ is already vastly superior to our current documentation.

@nworbmot If you have comments, inspirations and even better ideas, I think now's a good time!

Please don't merge as merge commit, but either squash it or allow me to rewrite the history slightly so we don't pull in the large immediate images.

…p travis]

- examples: - include plot of acdc meshed - rearrange scigrid example plots - introduction.rst: update plots

coroa · 2019-07-04T20:39:43Z

@fneum Ok, it's merged, can you do the readthedocs changes? And ping @nworbmot to update pypsa.org/documentation once it's all set!

fneum · 2019-07-05T07:23:07Z

https://pypsa.readthedocs.io has documentation for latest and stable version of PyPSA
webhook needs to be added for new readthedocs URL
@nworbmot instructions for setting up custom domain: https://docs.readthedocs.io/en/stable/custom_domains.html or alternatively https://pypsa.org/doc ->https://pypsa.readthedocs.io
If you have/create a readthedocs account, I can add you to the PyPSA readthedocs project such that not only I can make changes. DM me.

nworbmot · 2019-07-21T12:18:42Z

I've added a redirect to pypsa.org/doc/*, try e.g.
https://pypsa.org/doc/optimal_power_flow.html

fneum · 2019-07-21T12:37:29Z

Thanks, works for me!

[WIP] capital cost and underwater fraction update in clustering

fneum marked this pull request as ready for review May 28, 2019 12:18

coroa reviewed May 28, 2019

View reviewed changes

fneum added the enhancement label May 28, 2019

fneum self-assigned this May 28, 2019

fneum changed the title ~~WIP: augmentation of documentation~~ augmentation of documentation May 28, 2019

coroa mentioned this pull request May 29, 2019

Package PyPSA for conda with conda-forge #70

Closed

coroa reviewed May 29, 2019

View reviewed changes

environment_docs.yml Outdated Show resolved Hide resolved

pypsa/components.py Show resolved Hide resolved

pypsa/io.py Show resolved Hide resolved

doc/index.rst Outdated Show resolved Hide resolved

fneum added 11 commits July 4, 2019 22:19

WIP: augmentation of documentation

e8de6f2

add autodocs in all except design, components, pf, opf, conventions

46ac930

add numpydoc to setup and readthedocs.yml and improve documentation text

082bfc8

conda readthedocs environment

33e1902

environment_docs.yml include pypsa

cb599d3

use sphinx.ext.napoleon for numpydocs

6c1bb17

network_pf(): docstring conforms now to numpydoc format [skip travis]

01311e8

reordered content of sidebar and use automethod [skip travis]

006cc5f

fix bold font setting [skip travis]

4380cf2

build conda environment pypsa from directory + minor corrections [ski…

4d7043a

…p travis]

add conda badge [skip travis]

770d058

fneum and others added 2 commits July 4, 2019 22:20

minor formatting edit [skip travis]

5e953ef

Update plots in examples and introduction [skip travis]

3b89270

- examples: - include plot of acdc meshed - rearrange scigrid example plots - introduction.rst: update plots

coroa force-pushed the readthedocs branch from 5f94e27 to 3b89270 Compare July 4, 2019 20:28

coroa merged commit 8216767 into master Jul 4, 2019

fneum deleted the readthedocs branch July 5, 2019 07:16

fneum pushed a commit that referenced this pull request Mar 20, 2022

Merge pull request #71 from PyPSA/update_link_length

0c777fc

[WIP] capital cost and underwater fraction update in clustering

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

augmentation of documentation #71

augmentation of documentation #71

fneum commented May 24, 2019 •

edited

coroa commented May 26, 2019

FabianHofmann commented May 26, 2019

coroa commented May 27, 2019

fneum commented May 27, 2019

coroa commented May 28, 2019 •

edited

fneum commented May 28, 2019

coroa commented May 28, 2019

fneum commented May 28, 2019 •

edited

coroa left a comment •

edited

coroa left a comment

coroa commented May 29, 2019

FabianHofmann commented May 31, 2019

coroa commented May 31, 2019

coroa commented Jun 3, 2019

coroa commented Jul 4, 2019

fneum commented Jul 5, 2019

nworbmot commented Jul 21, 2019

fneum commented Jul 21, 2019

augmentation of documentation #71

augmentation of documentation #71

Conversation

fneum commented May 24, 2019 • edited

coroa commented May 26, 2019

FabianHofmann commented May 26, 2019

coroa commented May 27, 2019

fneum commented May 27, 2019

coroa commented May 28, 2019 • edited

fneum commented May 28, 2019

coroa commented May 28, 2019

fneum commented May 28, 2019 • edited

coroa left a comment • edited

Choose a reason for hiding this comment

coroa left a comment

Choose a reason for hiding this comment

coroa commented May 29, 2019

FabianHofmann commented May 31, 2019

coroa commented May 31, 2019

coroa commented Jun 3, 2019

coroa commented Jul 4, 2019

fneum commented Jul 5, 2019

nworbmot commented Jul 21, 2019

fneum commented Jul 21, 2019

fneum commented May 24, 2019 •

edited

coroa commented May 28, 2019 •

edited

fneum commented May 28, 2019 •

edited

coroa left a comment •

edited