More doc improvements and fixes

climlab · Nov 5, 2019 · 747303b · 747303b
1 parent a778c73
commit 747303b
Show file tree

Hide file tree

Showing 7 changed files with 56 additions and 58 deletions.
diff --git a/README.rst b/README.rst
@@ -72,33 +72,7 @@ Binaries are available for OSX, Linux, and Windows.
 
 Installing from source
 ~~~~~~~~~~~~~~~~~~~~~~
-If you do not use conda, you can install ``climlab`` from source with::
-
-    pip install climlab
-
-(which will download the latest stable release from the `pypi repository`_ and trigger the build process.)
-
-Alternatively, clone the source code repository with::
-
-    git clone https://github.com/brian-rose/climlab.git
-
-and, from the ``climlab`` directory, do::
-
-    python -m pip install . --no-deps -vv
-
-You will need a Fortran compiler on your system.
-The build has been tested with both gcc/gfortran and ifort (Linux)
-
-Installing from source without a Fortran compiler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Many parts of ``climlab`` are written in pure Python and should work on any system.
-Fortran builds are necessary for the RRTMG and CAM3 radiation schemes and for the Emanuel convection scheme.
-If you follow the instructions for installing from source (above) without a valid Fortran compiler,
-you should find that you can still::
-
-    import climlab
-
-and use most of the package. You will see warning messages about the missing components.
+Consult the documentation_ for detailed instructions.
 
 .. _conda: https://conda.io/docs/
 .. _`Anaconda Python`: https://www.continuum.io/downloads
@@ -125,9 +99,10 @@ Required
 - Python 2.7, 3.6, 3.7
 - numpy
 - scipy
-- xarray
-- future
+- xarray (for data i/o)
 - attrdict
+- future
+- requests
 
 
 Recommended for full functionality
@@ -145,6 +120,18 @@ To build from source and develop new code you will need some additional pieces
 - gfortran (OSX or linux) or flang (Windows)
 - pytest (to run the automated tests, important if you are developing new code)
 
+To build the docs, yet another list of requirements
+
+- sphinx
+- ipython
+- jupyter
+- future
+- sphinx_rtd_theme
+- nbsphinx
+- sphinxcontrib-bibtex
+- numpydoc
+- matplotlib
+
 `Anaconda Python`_ is highly recommended and will provide everything you need.
 See "Installing pre-built binaries with conda" above.
 

diff --git a/docs/source/contact.rst b/docs/source/contact.rst
@@ -15,7 +15,7 @@ Bugs can be reported through the `issue tracker <https://github.com/brian-rose/c
 
 
 The documentation was originally created by **Moritz Kreuzer**, Potsdam Institut for Climate Impact Research (PIK).
-Other contributers include
+Other contributors include
 
 - Ryan Abernathey
 - Christopher Cardinale
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -1,5 +1,8 @@
 .. highlight:: rst
 
+.. _`Contributing to CLIMLAB`:
+
+
 Contributing to CLIMLAB
 =======================
 
@@ -61,7 +64,7 @@ Contributions will happen through Pull Requests on github. You will need a free
 (choose a more descriptive name for your new feature).
 
 3. Work on your new feature, using ``git add`` to add your changes.
-4. Build and Test your modified code! See `Building and Testing CLIMLAB`_ below for instructions. Make sure to add new tests for your cool new feature.
+4. Build and Test your modified code! See below for instructions. Make sure to add new tests for your cool new feature.
 
 5. When your feature is complete and tested, commit your changes::
 
@@ -156,7 +159,10 @@ Special Caveat for Mac OSX only
 
 Method 1 and Method 2 both rely on gfortran supplied by conda. Currently for these to work on Mac OSX the user needs some old SDKs that are no longer provided by default from Apple, and that cannot be bundled automatically by conda due to licensing issues. `See here for discussion`_.
 
-The short answer is that you should download ``MacOSX10.9.sdk`` from <https://github.com/phracker/MacOSX-SDKs> or <https://github.com/devernay/xcodelegacy>, and save it at ``$HOME/opt/MacOSX10.9.sdk`` on your Mac.
+The short answer is that you should download ``MacOSX10.9.sdk`` from either of
+- <https://github.com/phracker/MacOSX-SDKs> or
+- <https://github.com/devernay/xcodelegacy>
+and save it at ``$HOME/opt/MacOSX10.9.sdk`` on your Mac.
 
 
 Method 3: Rolling your own fortran compiler

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -4,11 +4,11 @@ Installation
 ============
 
 Installing pre-built binaries with conda (Mac OSX, Linux, and Windows)
---------------------------
+----------------------------------------------------------------------
 By far the simplest and recommended way to install ``climlab`` is using conda_
 (which is the wonderful package manager that comes with `Anaconda Python`_).
 
-You can install ``climlab`` and all its dependencies with::
+You can install CLIMLAB and all its dependencies with::
 
     conda install -c conda-forge climlab
 
@@ -21,40 +21,44 @@ and then simply do::
     conda install climlab
 
 Binaries are available for OSX, Linux, and Windows.
-You may need to update your ``numpy`` if you are using are using a version prior to 1.11.
 
 For Windows, builds are available for 64-bit versions of Python 3.5 and Python 3.6, and will require numpy 1.14 or later.
 
 Installing from source
 ----------------------
-If you do not use conda, you can install ``climlab`` from source with::
+
+*This will only work if you have a properly configured Fortran compiler installed and available.*
+
+If you do not use conda, it is **possible** to install CLIMLAB from source with::
 
     pip install climlab
 
-(which will download the latest stable release from the `pypi repository`_ and trigger the build process.)
+which will download the latest stable release from the `pypi repository`_ and trigger the build process.
 
 Alternatively, clone the source code repository with::
 
     git clone https://github.com/brian-rose/climlab.git
 
 and, from the ``climlab`` directory, do::
 
-    python setup.py install
+    python -m pip install . --no-deps -vv
 
-You will need a Fortran compiler on your system.
-The build has been tested with both gcc/gfortran and ifort (Linux)
+Please see :ref:`Contributing to CLIMLAB` for more details about how to build from source.
 
 Installing from source without a Fortran compiler
--------------------------------------
+-------------------------------------------------
+
+Many parts of CLIMLAB are written in pure Python and should work on any system. Fortran builds are necessary for the Emanuel convection scheme and the RRTMG and CAM3 radiation schemes.
+
+If you obtain the source code repository and do this from the repository root::
+
+    python setup.py install
 
-Many parts of ``climlab`` are written in pure Python and should work on any system.
-Fortran builds are necessary for the RRTMG and CAM3 radiation schemes.
-If you follow the instructions for installing from source (above) without a valid Fortran compiler,
-you should find that you can still::
+You should then find that you can still::
 
     import climlab
 
-and use most of the package. You will see warning messages about the missing radiation components.
+and use most of the package. You will see warning messages about the missing components.
 
 .. _conda: https://conda.io/docs/
 .. _`Anaconda Python`: https://www.continuum.io/downloads
@@ -79,16 +83,18 @@ These are handled automatically if you install with conda_.
 
 Required
 ------------
-- Python 2.7, 3.5, 3.6, 3.7 (as of version 0.7.1)
-- ``numpy``
-- ``scipy``
-- ``xarray`` (for data i/o)
-- ``attrdict``
+- Python 2.7, 3.6, 3.7
+- numpy
+- scipy
+- xarray (for data i/o)
+- attrdict
+- future
+- requests
 
 Recommended for full functionality
----------------
-- ``numba`` (used for acceleration of some components)
-- ``pytest`` (to run the automated tests, important if you are developing new code)
+----------------------------------
+- numba (used for acceleration of some components)
+- pytest (to run the automated tests, important if you are developing new code)
 
 `Anaconda Python`_ is highly recommended and will provide everything you need.
 See "Installing pre-built binaries with conda" above.
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -23,7 +23,6 @@ and then simply do::
     conda install climlab
 
 Binaries are available for OSX, Linux, and Windows.
-You may need to update your ``numpy`` if you are using are using a version prior to 1.11
 
 
 Single-column Radiative-Convective model
@@ -55,4 +54,4 @@ RRTMG radiation scheme::
             print rcm.ASR - rcm.OLR
 
 .. _conda: https://conda.io/docs/
-.. _`Anaconda Python`: https://www.continuum.io/downloads
+.. _`Anaconda Python`: https://www.anaconda.com/distribution/
diff --git a/docs/source/support.rst b/docs/source/support.rst
@@ -1,7 +1,7 @@
 .. highlight:: rst
 
 Acknowledgement
-=======
+===============
 
 
 Development of CLIMLAB and associated documentation is partially supported

diff --git a/docs/source/xarray.rst b/docs/source/xarray.rst
@@ -1,7 +1,7 @@
 .. highlight:: rst
 
 Integration with ``xarray``
-=========================
+===========================
 
 xarray_ is a powerful Python package for geospatial data analysis.
 It provides ``DataArray`` and ``Dataset`` structures for self-describing gridded data.