Documentation before the first release

docs/dev_guide.rst

@@ -0,0 +1,97 @@
+.. _dev_guide:
+
+*****************
+Developer's Guide
+*****************
+
+Testing Guidelines
+------------------
+
+This section describes how to test the ``hvpy`` package.
+The testing framework used by ``hvpy`` is the `pytest <https://docs.pytest.org/>`__ framework.
+
+.. _running-tests:
+
+Running Tests
+^^^^^^^^^^^^^
+
+There are currently two different ways to invoke ``hvpy`` tests.
+
+``tox``
+=======
+
+The most robust way to run the tests (which can also be the slowest) is to make use of `Tox <https://tox.readthedocs.io/en/latest/>`__, which is a general purpose tool for automating Python testing.
+One of the benefits of ``tox`` is that it first creates a source distribution of the package being tested, and installs it into a new virtual environment, along with any dependencies that are declared in the package, before running the tests.
+This can therefore catch issues related to undeclared package data, or missing dependencies.
+Since we use tox to run many of the tests on continuous integration services, it can also be used in many cases to reproduce issues seen on those services.
+
+To run the tests with ``tox``, first make sure that ``tox`` is installed::
+
+    pip install tox
+
+You can see a list of available test environments with::
+
+    tox -l -v
+
+which will also explain what each of them does.
+
+You can also run checks or commands not directly related to tests - for instance::
+
+    tox -e codestyle
+
+will run checks on the code style using precommit hooks.
+
+``pytest``
+==========
+
+The test suite can also be run directly from the native ``pytest`` command, which is generally faster than using tox for iterative development.
+In this case, it is important for developers to be aware that they must manually rebuild any extensions by running::
+
+    pip install -e ".[test]"
+
+before running the test with pytest with::
+
+    pytest
+
+To run all the test in the ``hvpy`` package, you can use::
+
+    pytest -c hvpy
+
+you can also run specific test functions with::
+
+    pytest -c hvpy -k test_function
+
+.. _hvpy-doc-building:
+
+Building Documentation
+----------------------
+
+.. note::
+
+    Building the documentation is not necessary unless you are writing new documentation or do not have internet access, because the latest versions of ``hvpy``'s should be available at `hvpy.readthedocs.io <https://hvpy.readthedocs.io/>`__.
+
+This does not include `Graphviz <http://www.graphviz.org>`__.
+If you do not install this package separately then the documentation build process will produce a very large number of lengthy warnings (which can obscure bona fide warnings) and also not generate inheritance graphs.
+
+Building
+^^^^^^^^
+
+There are two ways to build the ``hvpy`` documentation.
+The easiest way is to execute the following tox command (from the ``hvpy`` source directory)::
+
+    tox -e build_docs
+
+If you do this, you do not need to install any of the documentation dependencies as this will be done automatically.
+The documentation will be built in the ``docs/_build/html`` directory, and can be read by pointing a web browser to ``docs/_build/html/index.html``.
+
+Alternatively, you can do::
+
+    cd docs
+    make html
+
+And the documentation will be generated in the same location.
+Note that this uses the installed version of ``hvpy``, so if you want to make sure the current repository version is used, you will need to install it with::
+
+    pip install -e ".[docs]"
+
+before changing to the ``docs`` directory.

docs/guide.rst

@@ -2,4 +2,4 @@
 User Guide
 **********
 
-This is how you install and use ``hvpy``.
+This user guide provides a walkthrough of the major features in the ``hvpy`` package.

docs/index.rst

@@ -1,11 +1,32 @@
-******************
-hvpy Documentation
-******************
+**********************
+``hvpy`` Documentation
+**********************
 
-This is the documentation for ``hvpy``.
+``hvpy`` is a Python package which provides a high-level interface the `helioviewer.org <https://helioviewer.org>`__ `API <https://api.helioviewer.org/docs/v2/>`__.
 
 .. toctree::
    :maxdepth: 2
 
+   installation
    guide
    api
+   dev_guide
+
+Contribute to ``hvpy``
+----------------------
+
+Reporting Issues or Requesting Features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have found a bug in ``hvpy`` please report it.
+The preferred way to report issues is to create an issue on the ``hvpy`` `GitHub Issue page <https://github.com/Helioviewer-Project/python-api/issues>`__.
+
+Contribute code or documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+People who wish to contribute to this package should fork the `GitHub repository <https://github.com/Helioviewer-Project/python-api>`__.
+
+You need to install the development version of the package in order to make and test changes.
+See the :ref:`obtaining_the_source` section for details.
+
+You may also want to familiarize yourself with the :ref:`dev_guide` for ``hvpy``.

docs/installation.rst

@@ -0,0 +1,50 @@
+.. _installation:
+
+************
+Installation
+************
+
+If you are new to Python and/or do not have familiarity with `Python virtual environments <https://docs.python.org/3/tutorial/venv.html>`__, then we recommend starting by installing `miniforge <https://github.com/conda-forge/miniforge#miniforge3>`__.
+This works on all platforms (Linux, Mac, Windows) and installs a full-featured Python environment in your user directory without requiring root privileges.
+
+Using pip
+---------
+
+To install ``hvpy`` with `pip <https://pip.pypa.io/en/stable/>`__, run ::
+
+    pip install hvpy
+
+.. _conda_install:
+
+Using Conda
+-----------
+
+To install ``hvpy`` using `conda <https://docs.conda.io/projects/conda/en/latest/>`__ run ::
+
+    conda install -c conda-forge hvpy
+
+.. _obtaining_the_source:
+
+Obtaining the Source Package
+----------------------------
+
+Source Package
+^^^^^^^^^^^^^^
+
+The latest stable source package for ``hvpy`` can be `downloaded at pypi.org <https://pypi.org/project/hvpy>`__.
+
+Development Repository
+^^^^^^^^^^^^^^^^^^^^^^
+
+The latest development version of ``hvpy`` can be cloned from `GitHub <https://github.com/Helioviewer-Project/python-api/>`__. ::
+
+   git clone git@github.com:Helioviewer-Project/python-api.git
+
+Installing from Source
+^^^^^^^^^^^^^^^^^^^^^^
+
+To build and install ``hvpy`` (from the root of the source tree) ::
+
+    pip install -e ".[tests,dev]"
+
+which installs ``hvpy`` in development mode, this means that a change in the source code is immediately reflected.