Skip to content

Commit a0f42a9

Browse files
emiliomemiliom
authored
Merge pull request #163 from emiliom/docsphinx
Updates to sphinx docs Self merging, as this PR only impacts the documentation, not the code base.
2 parents d332e0c + 948d8cc commit a0f42a9

File tree

6 files changed

+200
-120
lines changed

6 files changed

+200
-120
lines changed

‎docs/source/contribute.rst

+47-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,55 @@
1-
Contribute to Documentation
1+
Contributing
22
============================
33

4+
You can help with ODM2 Python API by contributing code, helping with the documentation, or engaging the team via `GitHub issues <https://github.com/ODM2/ODM2PythonAPI/issues>`_ (questions, solutions, etc).
5+
6+
7+
Install the development version from GitHub
8+
--------------------------------------------
9+
10+
The latest development version is found in the ``development`` branch of the github repository. We follow the `Gitflow workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ for development.
11+
12+
1. Download both ``requirements.txt`` and ``requirements-dev.txt``.
13+
14+
.. code-block:: bash
15+
16+
wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements.txt
17+
wget https://raw.githubusercontent.com/ODM2/ODM2PythonAPI/master/requirements-dev.txt
18+
19+
2. Create conda environment ``odm2api_dev`` from the two ``requirements*`` text files.
20+
21+
.. code-block:: bash
22+
23+
conda create -n odm2api_dev -c conda-forge python=2.7 --file requirements.txt --file requirements-dev.txt
24+
25+
3. Activate conda environment.
26+
- MacOSX/Linux:
27+
28+
.. code-block:: bash
29+
30+
source activate odm2api_dev
31+
32+
- Windows:
33+
34+
.. code-block:: bash
35+
36+
activate odm2api_dev
37+
38+
4. Install the latest commit from the development branch
39+
40+
.. code-block:: bash
41+
42+
pip install git+https://github.com/ODM2/ODM2PythonAPI.git@development#egg=odm2api
43+
44+
45+
Contribute to documentation
46+
----------------------------------
47+
448
This guide is a reference on how to contribute to ODM2 Documentation effort
549
for the many `ODM2 Software Ecosystem <https://github.com/ODM2/odm2-software-ecosystem>`__.
650

751
Conventions
8-
-----------
52+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
953

1054
There are a few conventions that should be followed
1155
when writing docstrings within the code:
@@ -30,7 +74,7 @@ Please add any additional conventions that you think should be in place
3074
within `the github issue #106 <https://github.com/ODM2/ODM2PythonAPI/issues/106>`__.
3175

3276
Pull requests
33-
-------------
77+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3478

3579
Once changes has been in place within your forked copy of the repository
3680
you are working on, please create a pull request to add your contribution

‎docs/source/getstarted.rst

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
Get Started
2+
============
3+
4+
5+
Install the latest release with conda
6+
-------------------------------------
7+
8+
conda
9+
^^^^^
10+
11+
The easiest and most reliable way to install the ODM2 Python API
12+
(``odm2api``) is using the `Conda package management
13+
system <https://conda.io/docs/>`__ via either
14+
`Anaconda <https://www.anaconda.com/download/>`__ or
15+
`Miniconda <https://conda.io/miniconda.html>`__. To start using
16+
conda (if it's not your system default), add conda to the PATH; on
17+
OS X and Linux, it's something like
18+
``export PATH=$HOME/miniconda3/bin:$PATH``, but the exact path may vary.
19+
20+
To activate a conda environment, say, "myenv":
21+
22+
.. code-block:: bash
23+
24+
activate myenv # On Windows
25+
source activate myenv # On MacOSX or Linux
26+
27+
**Note:** ``odm2api`` currently is only tested on Python 2.7. Some
28+
changes have been made to support Python 3.x, but they haven't been
29+
tested thoroughly.
30+
31+
Install the conda package
32+
^^^^^^^^^^^^^^^^^^^^^^^^^
33+
34+
The `latest release <https://github.com/ODM2/ODM2PythonAPI/releases>`_ is available
35+
as a package on the `conda-forge anaconda.org channel <https://anaconda.org/conda-forge/odm2api>`_
36+
for all major OS platforms (linux, OS X, win32/win64). To install it on
37+
an existing conda environment:
38+
39+
::
40+
41+
conda install -c conda-forge odm2api
42+
43+
All dependencies are installed, including Pandas and its dependencies
44+
(numpy, etc).
45+
46+
To create a new environment "myenv" with the ``odm2api`` package:
47+
48+
::
49+
50+
conda create -n myenv -c conda-forge python=2.7 odm2api
51+
52+
53+
Code examples
54+
-------------
55+
56+
Connecting to an ODM2 database
57+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
58+
59+
Connect to an ODM2 database and open the connection for reading.
60+
61+
.. code-block:: python
62+
63+
from odm2api.ODMconnection import dbconnection
64+
import odm2api.services.readService as odm2rs
65+
66+
# A SQLite file-based connection
67+
session_factory = dbconnection.createConnection('sqlite',
68+
'/myfilepath/odm2db.sqlite')
69+
read = odm2rs.ReadODM2(session_factory)
70+
71+
# A connection to a server-based database system
72+
db_credentials = {
73+
'address': 'ip-or-domainname',
74+
'db': 'dbname',
75+
'user': 'dbuser',
76+
'password': 'password'
77+
}
78+
session_factory = dbconnection.createConnection('postgresql',
79+
**db_credentials)
80+
read = odm2rs.ReadODM2(session_factory)
81+
82+
83+
Updating an entity (table)
84+
^^^^^^^^^^^^^^^^^^^^^^^^^^
85+
86+
The `update services <https://github.com/ODM2/ODM2PythonAPI/blob/master/odm2api/services/updateService.py>`_
87+
have not been fleshed out at this time, for the most part. However, updates can be easily
88+
accomplished by reusing the connection setup at the start of an odm2api session,
89+
then constructing and issuing a direct ``SQL UPDATE`` statement, like this:
90+
91+
.. code-block:: python
92+
93+
from odm2api.ODMconnection import dbconnection
94+
95+
session_factory = dbconnection.createConnection('postgresql',
96+
**db_cred)
97+
DBSession = session_factory.getSession()
98+
99+
sq_str = " UPDATE mytable SET variablecode = 'xyz' WHERE variablecode = 'abc' "
100+
DBSession.execute(sql_str)
101+
DBSession.commit()
102+
103+
104+
Sample Jupyter notebooks
105+
------------------------
106+
107+
These two notebooks are complete, extended examples that illustrate reading from ODM2 databases and using the resulting data and metadata. They use SQLite ODM2 file databases that can be `downloaded here <https://github.com/ODM2/ODM2PythonAPI/tree/master/Examples/data>`_.
108+
A conda environment to run these notebooks can be created with the conda environment file
109+
`clientenvironment.yml <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/clientenvironment.yml>`_.
110+
111+
1. `WaterQualityMeasurements_RetrieveVisualize.ipynb <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/WaterQualityMeasurements_RetrieveVisualize.ipynb>`_
112+
113+
2. `TimeSeries_RetrieveVisualize.ipynb <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/TimeSeries_RetrieveVisualize.ipynb>`_

‎docs/source/index.rst

+7-9
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,24 @@
1-
ODM2 Python API
2-
===============
1+
ODM2 Python API (odm2api)
2+
=========================
33

4-
A Python-based application programmer's interface for the `Observations Data Model 2 (ODM2) <http://www.odm2.org>`__.
4+
A Python-based application programmer's interface for the `Observations Data Model 2 (ODM2) <http://www.odm2.org>`__. Development of ``odm2api`` is done at `<https://github.com/ODM2/ODM2PythonAPI/>`_.
55

66
.. toctree::
77
:maxdepth: 2
88
:caption: Contents:
99

10-
installing
11-
modules
10+
getstarted
1211
odm2models
13-
credits
12+
modules
1413
contribute
14+
credits
1515

16-
Indices and tables
16+
Indices and Search
1717
==================
1818

1919
.. toctree::
2020
:maxdepth: 2
2121

22-
models
23-
2422
* :ref:`genindex`
2523
* :ref:`modindex`
2624
* :ref:`search`

‎docs/source/installing.rst

-81
This file was deleted.

‎docs/source/models.rst

-27
This file was deleted.

‎docs/source/odm2models.rst

+33
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,39 @@
11
ODM2 Models
22
===========
33

4+
ODM2 is organized with a "core" schema and multiple "extension" schemas that
5+
extend the functionality of the core. The following sections cover some overarching concepts
6+
for ODM2 and then focus on specific entities within the ODM2 Core schema and ODM2's extension schemas.
7+
8+
ODM2Core entities
9+
------------------
10+
11+
The following are entities in the `ODM2 Core Schema <http://odm2.github.io/ODM2/schemas/ODM2_Current/diagrams/ODM2Core.html>`__:
12+
13+
.. autosummary::
14+
15+
odm2api.models.ActionBy
16+
odm2api.models.Actions
17+
odm2api.models.Affiliations
18+
odm2api.models.DataSets
19+
odm2api.models.FeatureActions
20+
odm2api.models.Methods
21+
odm2api.models.Organizations
22+
odm2api.models.People
23+
odm2api.models.ProcessingLevels
24+
odm2api.models.RelatedActions
25+
odm2api.models.Results
26+
odm2api.models.SamplingFeatures
27+
odm2api.models.TaxonomicClassifiers
28+
odm2api.models.Units
29+
odm2api.models.Variables
30+
31+
32+
All ODM2 models
33+
----------------
34+
35+
API descriptions for `all ODM2 models (entities) <http://odm2.github.io/ODM2/schemas/ODM2_Current/schemas/index.html>`_.
36+
437
.. automodule:: odm2api.models
538
:members:
639
:undoc-members:

0 commit comments

Comments
 (0)