Merge pull request #20 from pysat/add_docs

DOCS: added basic doc files

.zenodo.json

@@ -9,6 +9,6 @@
         "affiliation": "WORKPLACE", 
         "name": "AUTHOR LAST, AUTHOR FIRST, AUTHOR MIDDLE",
         "orcid": "ORCID"
-      }, 
+      }
     ]
 }

docs/acknowledgements.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../ACKNOWLEDGEMENTS.md

docs/citing.rst

@@ -0,0 +1,30 @@
+Citation Guidelines
+===================
+
+When publishing work that uses PACKAGE, please cite the package and
+any package it depends on that plays an important role in your analysis.
+Specifying which version of PACKAGE used will also improve the
+reproducibility of your presented results.
+
+PACKAGENAME
+-----------
+
+The most recent citation can be found at `Zenodo <link>`_.  The examples here
+are from the first release.
+
+* Surname, E. G., et al. (20XX).
+  PACKAGENAME: Initial Release (Version 0.0.1). Zenodo.
+  doi:10.xxxx/zenodo.xxxxxxx
+
+.. code-block:: latex
+
+    @Misc{PACKAGE,
+          author = {Surname, E. G. and Coauthor, I. E.},
+	  title  = {PACKAGENAME: Initial Release},
+  	  year   = {20XX},
+	  date   = {20XX-XX-XX},
+	  url    = {https://github.com/PACKAGE_REPOSITORY},
+	  doi    = {10.xxxx/zenodo.xxxxxxx},
+	  publisher = {Zenodo},
+	  version = {v0.0.1},
+	  }

docs/conf.py

@@ -79,9 +79,6 @@
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-doc_dir = os.path.abspath(os.path.dirname(__file__))
-with open(os.path.join(doc_dir, "..", project, "version.txt"), "r") as fin:
-    version = fin.read().strip()
 release = '{:s}-alpha'.format(version)  # Include alpha/beta/rc tags.
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -184,4 +181,4 @@
 epub_exclude_files = ['search.html']
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'<name>': ('https://docs.python.org/', None)}

docs/develop_guide.rst

@@ -0,0 +1,6 @@
+Guide for Developers
+====================
+
+.. toctree::
+   develop_guide/code_of_conduct.rst
+   develop_guide/contributing.rst

docs/develop_guide/code_of_conduct.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CODE_OF_CONDUCT.md

docs/develop_guide/contributing.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CONTRIBUTING.md

docs/history.rst

@@ -0,0 +1,3 @@
+.. _hist:
+
+.. mdinclude:: ../CHANGELOG.md

docs/index.rst

@@ -0,0 +1,27 @@
+.. PACKAGE documentation main file.  Remember that it should at least
+   contain the root `toctree` directive.
+
+Welcome to the PACKAGENAME documentation
+========================================
+
+This documentation describes the PACKAGENAME module, which contains
+routines to DO AMAZING THINGS.
+
+.. toctree::
+   :maxdepth: 2
+
+   overview.rst
+   installation.rst
+   citing.rst
+   develop_guide.rst
+   history.rst
+   acknowledgements.rst
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,80 @@
+.. _install:
+
+Installation
+============
+
+The following instructions will allow you to install PACKAGE
+
+
+.. _install-prereq:
+
+Prerequisites
+-------------
+
+.. image:: figures/poweredbypysat.png
+    :width: 150px
+    :align: right
+    :alt: powered by pysat Logo, blue planet with orbiting python
+
+
+PACKAGE uses common Python modules, as well as modules developed by
+and for the Space Physics community.  This module officially supports
+Python 3.6+.
+
+ ============== =================
+ Common modules Community modules
+ ============== =================
+  numpy         pysat >= 3.1.0
+  pandas
+  xarray
+ ============== =================
+
+
+.. _install-opt:
+
+
+Installation Options
+--------------------
+
+
+.. _install-opt-pip:
+
+PyPi
+^^^^
+All official pysatSpaceWeather releases are `available <link>`_ through the
+PyPi package manager.
+::
+
+
+   pip install PACKAGENAME
+
+
+
+.. _install-opt-git:
+
+GitHub
+^^^^^^
+You can keep up to date with the latest changes at the GitHub repository.
+
+1. Clone the git repository
+::
+
+
+   git clone https://github.com/PACKAGE_REPOSITORY
+
+
+2. Install PACKAGENAME:
+   Change directories into the repository folder and run the setup.py file.
+   There are a few ways you can do this:
+
+   A. Install on the system (will install locally without root privileges)::
+
+
+        python -m build
+	pip install .
+
+   B. Install with the intent to develop locally::
+
+
+        python -m build
+	pip install -e .

docs/overview.rst

@@ -0,0 +1,9 @@
+Overview
+========
+
+DESCRIPTION OF PACKAGE
+
+.. image:: figures/packagename_logo.jpg
+    :width: 400px
+    :align: center
+    :alt: PACKAGENAME Logo, A planet with a python orbitting and the module name superimposed.