WIP: augmentation of documentation

matzech · Jul 4, 2019 · e8de6f2 · e8de6f2
1 parent 8a1dd06
commit e8de6f2
Show file tree

Hide file tree

Showing 8 changed files with 48 additions and 34 deletions.
diff --git a/doc/_static/theme_overrides.css b/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: 880px !important;
+ }
+ }
diff --git a/doc/conf.py b/doc/conf.py
@@ -33,8 +33,8 @@
  'sphinx.ext.autodoc',
  'sphinx.ext.intersphinx',
  'sphinx.ext.todo',
-# 'sphinx.ext.mathjax',
- 'sphinx.ext.imgmath',
+ 'sphinx.ext.mathjax',
+# 'sphinx.ext.imgmath',
 # 'sphinxcontrib.tikz',
 # 'rinoh.frontend.sphinx',
  'sphinx.ext.imgconverter', # for SVG conversion
@@ -117,12 +117,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': '',
+ '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 +154,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.

diff --git a/doc/developers.rst → doc/contributing.rst b/doc/developers.rst → doc/contributing.rst
@@ -1,5 +1,5 @@
 #######################
-Developers
+Contributing
 #######################
 
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -27,9 +27,8 @@ Contents:
  troubleshooting
  unit_testing
  comparable_software
- developers
+ contributing
  release_notes
- mailing_list
 
 Indices and tables
 ==================

diff --git a/doc/introduction.rst b/doc/introduction.rst
@@ -191,6 +191,13 @@ Mailing list
 PyPSA has a Google Group `forum / mailing list
 <https://groups.google.com/group/pypsa>`_.
 
+Anyone can join and anyone can read the posts; only members of the
+group can post to the list.
+
+
+The intention is to have a place where announcements of new releases
+can be made and to discuss issues and suggest/contribute features for
+future development.
 
 
 Citing PyPSA

diff --git a/doc/mailing_list.rst b/doc/mailing_list.rst
diff --git a/doc/quick_start.rst b/doc/quick_start.rst
@@ -2,22 +2,13 @@
 Quick Start
 ###########################
 
+For installation instructions see :doc:`installation`.
+
 See also the existing :doc:`examples` and the example Jupyter
 notebooks at `https://www.pypsa.org/examples/
 <https://www.pypsa.org/examples/>`_.
 
 
-Installation
-============
-
-For full installation instructions see :doc:`installation`.
-
-If you have the Python package installer ``pip`` then just run::
-
- pip install pypsa
-
-
-
 Build a minimal network for power flow
 ======================================
 

diff --git a/pypsa/component_attrs/networks.csv b/pypsa/component_attrs/networks.csv
@@ -1,6 +1,6 @@
 attribute,type,unit,default,description,status
 name,string,n/a,n/a,Unique name,Input (required)
-snapshots,list or pandas.Index,n/a,"[""now""]","List of snapshots or time steps. All time-dependent series quantities are indexed by ``network.snapshots``. To reset the snapshots, call ``network.set_snapshots(new_snapshots)``.",Input (optional)
+snapshots,list or pandas.Index,n/a,"[""now""]","List of snapshots or time steps. All time-dependent series quantities are indexed by ``network.snapshots``. To reset the snapshots, call ``network.set_snapshots(new)``.",Input (optional)
 snapshot_weightings,pandas.Series, hours , 1. ,"The weighting applied to each snapshot, so that snapshots can represent more than one hour or fractions of one hour. This weighting is used to weight snapshots in the LOPF objective function, to determine the state of charge change for storage units and for calculating global constraints.",Input (optional)
 now,any,n/a,"""now""","The current snapshot/time/scenario, relevant e.g. when ``network.pf()`` is called without a snapshot argument.",Input (optional)
 srid,integer,n/a,4326,"Spatial Reference System Indentifier for x,y coordinates of buses. It defaults to standard longitude and latitude.",Input (optional)
@@ -11,4 +11,4 @@ lines_t,dictionary of pandas.DataFrames,n/a,n/a,"All time-dependent line informa
 components,pandas.DataFrame,n/a,n/a,"For each component type (buses, lines, etc.): static component information compiled by PyPSA from inputs. Index is component names, columns are component attributes.",Output
 components_t,dictionary of pandas.DataFrames,n/a,n/a,"For each component type (buses, lines, etc.): time-dependent component information compiled by PyPSA from inputs. Dictionary keys are time-dependent series attributes, index is network.snapshots, columns are component names.",Output
 branches(),pandas.DataFrame,n/a,n/a,"Dynamically generated concatenation of branch DataFrames: network.lines, network.transformers and network.links. Note that this is a copy and therefore changing entries will NOT update the original.",Output
-graph(),networkx.OrderedMultiGraph,n/a,n/a,Graph of network.,Output
+graph(),networkx. OrderedMultiGraph,n/a,n/a,Graph of network.,Output