Merge pull request PyPSA#71 from PyPSA/readthedocs

Augmentation of documentation

.readthedocs.yml

@@ -0,0 +1,4 @@
+version: 2
+
+conda:
+    environment: environment_docs.yml

README.rst

@@ -1,4 +1,4 @@
-|badge_travis| |badge_pypi| |badge_license|
+|badge_pypi| |badge_conda| |badge_travis| |badge_docs| |badge_license| |link-latest-doi|
 
 -----
 
@@ -249,8 +249,16 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     :alt: PyPI version
 
 .. |badge_license| image:: https://img.shields.io/pypi/l/pypsa.svg
-    :target: #license
+    :target: License
 
 .. |badge_travis| image:: https://img.shields.io/travis/PyPSA/PyPSA/master.svg
     :target: https://travis-ci.org/PyPSA/PyPSA
     :alt: Build status on Linux
+
+.. |badge_docs| image:: https://readthedocs.org/projects/pypsa-readthedocs/badge/?version=readthedocs
+    :target: https://pypsa-readthedocs.readthedocs.io/en/readthedocs/?badge=readthedocs
+    :alt: Documentation Status
+
+.. |badge_conda| image:: https://img.shields.io/conda/vn/conda-forge/pypsa.svg
+    :target: https://anaconda.org/conda-forge/pypsa
+    :alt: Conda version

doc/_static/theme_overrides.css

@@ -0,0 +1,19 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td {
+       /* !important prevents the common CSS stylesheets from overriding
+          this as on RTD they are loaded after this stylesheet */
+       white-space: normal !important;
+       /* background: #eeeeee !important; */
+    }
+
+    .wy-table-responsive {
+       max-width: 100%;
+       overflow: visible !important;
+    }
+
+    .wy-nav-content {
+        max-width: 910px !important;
+    }
+ }

doc/api_reference.rst

@@ -0,0 +1,16 @@
+######################
+API Reference
+######################
+
+Network
+-------
+
+.. autoclass:: pypsa.Network
+    :members:
+
+
+Sub-Network
+-----------
+
+.. autoclass:: pypsa.SubNetwork
+    :members:

doc/comparable_software.rst

@@ -52,18 +52,6 @@ Free software
 
 `vSPD <https://github.com/ElectricityAuthority/vSPD>`_ - Vectorised Scheduling, Pricing and Dispatch (vSPD) - an audited, mathematical replica of SPD, the pricing and dispatch engine used in the New Zealand electricity market.
 
-PYPOWER
--------
-
-PyPSA is compared to `PYPOWER <https://github.com/rwl/PYPOWER>`_ in the following table:
-
-
-.. csv-table::
-   :header-rows: 1
-   :file: pypower.csv
-
-
-
 
 Non-free software
 =================
@@ -80,3 +68,14 @@ PowerWorld
 INTEGRAL
 
 `PLEXOS <https://energyexemplar.com/software/plexos-desktop-edition/>`_
+
+
+Comparison with selected packages
+===================================
+
+PyPSA is compared to `PYPOWER <https://github.com/rwl/PYPOWER>`_ in the following table:
+
+
+.. csv-table::
+   :header-rows: 1
+   :file: pypower.csv

doc/components.rst

@@ -56,7 +56,6 @@ has the major functions as methods, such as ``network.lopf()`` and
    :file: ../pypsa/component_attrs/networks.csv
 
 
-
 Sub-Network
 ===========
 
@@ -118,7 +117,7 @@ table, the canonical example being CO2 emissions of the carrier
 relevant for limits on CO2 emissions.
 
 
-(NB: In versions of PyPSA < 0.6.0, this was called Source.)
+.. note:: In versions of PyPSA < 0.6.0, this was called Source.
 
 
 .. csv-table::
@@ -145,8 +144,7 @@ after conversion), "generation capacity" (for limits on total capacity
 expansion of given carriers) and "transmission capacity" (for limits
 on the total expansion of lines and links).
 
-Global constraints were added in PyPSA 0.10.0 and replace the ad hoc
-``network.co2_limit`` attribute.
+.. note:: Global constraints were added in PyPSA 0.10.0 and replace the ad hoc ``network.co2_limit`` attribute.
 
 
 .. csv-table::
@@ -422,12 +420,7 @@ power flow: a bidirectional point-to-point HVDC link, a unidirectional
 lossy HVDC link, a converter between an AC and a DC network, a heat
 pump or resistive heater from an AC/DC bus to a heat bus, etc.
 
-NB: ``Link`` has replaced the ``Converter`` component for linking AC
-with DC buses and the ``TransportLink`` component for providing
-controllable flows between AC buses. If you want to replace
-``Converter`` and ``TransportLink`` components in your old code, use
-the ``Link`` with ``efficiency = 1``, ``marginal_cost = 0``,
-``p_min_pu = -1``, ``p_max_pu = 1`` and ``p_nom* = s_nom*``.
+.. note:: ``Link`` has replaced the ``Converter`` component for linking AC with DC buses and the ``TransportLink`` component for providing controllable flows between AC buses. If you want to replace ``Converter`` and ``TransportLink`` components in your old code, use the ``Link`` with ``efficiency = 1``, ``marginal_cost = 0``, ``p_min_pu = -1``, ``p_max_pu = 1`` and ``p_nom* = s_nom*``.
 
 .. csv-table::
    :header-rows: 1

doc/conf.py

@@ -31,15 +31,20 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-#    'sphinx.ext.mathjax',
-    'sphinx.ext.imgmath',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+#    'sphinx.ext.pngmath',
 #    'sphinxcontrib.tikz',
-#    'rinoh.frontend.sphinx',
+    #'rinoh.frontend.sphinx',
     'sphinx.ext.imgconverter', # for SVG conversion
 ]
 
+autodoc_default_flags = ['members']
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -117,12 +122,18 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'canonical_url': 'https://www.pypsa.org/doc',
+    'display_version': True,
+    'sticky_navigation': True,
+    #'style_nav_header_background': '#009682',
+}
+
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -148,6 +159,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+}
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

doc/contingency_analysis.rst

@@ -62,7 +62,7 @@ The diagonal entries of the BODF are simply:
 .. math::
    BODF_{bb} = -1
 
-
+.. automethod:: pypsa.SubNetwork.calculate_BODF
 
 Linear Power Flow Contingency Analysis
 ======================================
@@ -72,9 +72,7 @@ case linear power flow (LPF) with no outages for ``snapshot``, and
 then cycles through the list of branches in ``branch_outages`` and
 computes the line flows after the outage of that branch using the BODF.
 
-The function returns a pandas.DataFrame ``p0`` with the flows in each
-case in each column of the DataFrame.
-
+.. automethod:: pypsa.Network.lpf_contingency
 
 
 Security-Constrained Linear Optimal Power Flow (SCLOPF)
@@ -86,15 +84,14 @@ the Linear Optimal Power Flow (LOPF) described in
 branches may not become overloaded after the outage of a selection of
 branches.
 
-The SCLOPF is called with the method::
+The SCLOPF is called with the method
 
-    network.sclopf(snapshots,branch_outages,**kwargs)
+.. automethod:: pypsa.Network.sclopf
 
-where ``branch_outages`` is a list of the branches whose outages
-should not overload the network. ``**kwargs`` are all the same
-arguments that may be passed to ``network.lopf()``. (Note that
+
+Note that
 ``network.sclopf()`` is implemented by adding a function to
-``network.lopf()`` via the ``extra_functionality`` keyword.)
+``network.lopf()`` via the ``extra_functionality`` keyword.
 
 
 For each potential outage of a branch :math:`c` add a set of
@@ -107,11 +104,3 @@ they do not become overloaded beyond their capacity :math:`F_b`:
 
 
 This applies for all snapshots :math:`t` considered in the optimisation.
-
-
-
-
-Inputs and Outputs
-------------------
-
-See LOPF in :doc:`optimal_power_flow`.

doc/developers.rst → doc/contributing.rst

@@ -1,10 +1,11 @@
 #######################
-Developers
+Contributing
 #######################
 
 
 We strongly welcome anyone interested in contributing to this project.
 
 Submit pull requests / issues to the `github repository <https://github.com/PyPSA/PyPSA>`_.
 
-Join the :doc:`mailing_list`.
+Join the `mailing list
+<https://groups.google.com/group/pypsa>`_.