diff --git a/docs/dev_guide.rst b/docs/dev_guide.rst new file mode 100644 index 0000000..40d891f --- /dev/null +++ b/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 `__ 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 `__, 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 `__. + +This does not include `Graphviz `__. +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. diff --git a/docs/guide.rst b/docs/guide.rst index 5105b85..25d4288 100644 --- a/docs/guide.rst +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 1bbaec2..7dfa922 100644 --- a/docs/index.rst +++ b/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 `__ `API `__. .. 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 `__. + +Contribute code or documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +People who wish to contribute to this package should fork the `GitHub repository `__. + +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``. diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..e9b8213 --- /dev/null +++ b/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 `__, then we recommend starting by installing `miniforge `__. +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 `__, run :: + + pip install hvpy + +.. _conda_install: + +Using Conda +----------- + +To install ``hvpy`` using `conda `__ 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 `__. + +Development Repository +^^^^^^^^^^^^^^^^^^^^^^ + +The latest development version of ``hvpy`` can be cloned from `GitHub `__. :: + + 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.