Skip to content

Commit

Permalink
Merge pull request #149 from JonathanWenger/dev-branch-deletion
Browse files Browse the repository at this point in the history
Remove all references to the development branch
  • Loading branch information
JonathanWenger authored Aug 18, 2020
2 parents a05f8dd + 2ddc3bc commit f0b94f0
Show file tree
Hide file tree
Showing 8 changed files with 92 additions and 49 deletions.
50 changes: 33 additions & 17 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Contributions to ProbNum are very welcome. Before getting started make sure to read the following guidelines.

All contributions to ProbNum should be made via pull requests (PR) to the
[development branch](https://github.com/probabilistic-numerics/probnum/tree/development) on GitHub. Some suggestions for
[master branch](https://github.com/probabilistic-numerics/probnum/tree/master) on GitHub. Some suggestions for
a good PR are:

- implements or fixes one functionality;
Expand All @@ -17,7 +17,9 @@ for detailed instructions.

## Getting Started

Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your forked repository describing the feature you would like to implement. You can now get started writing code in your new branch. Make sure to keep the following best practices regarding code quality in mind.
Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your
forked repository describing the feature you would like to implement. You can now get started writing code in your new
branch. Make sure to keep the following best practices regarding code quality in mind.

### Code Quality

Expand All @@ -35,34 +37,43 @@ For all of the above the existing ProbNum code is a good initial reference point

### Using Tox

Probnum uses [tox](https://tox.readthedocs.io/en/latest/) in its [continuous integration (CI)](#continuous-integration) pipeline to run tests and to build documentation. Under the hood, tox builds virtual environments following the specifications in `./tox.ini` in order to run tests across multiple python versions, while making sure that all the necessary dependencies are installed. Using tox unifies the *local* development process with CI, such that local test results should match the outcomes of Travis's builds more closely. This ensures that your pull request can be merged seemlessly into ProbNum's codebase.
Probnum uses [tox](https://tox.readthedocs.io/en/latest/) in its [continuous integration (CI)](#continuous-integration)
pipeline to run tests and to build documentation. Under the hood, tox builds virtual environments following the
specifications in `./tox.ini` in order to run tests across multiple python versions, while making sure that all the
necessary dependencies are installed. Using tox unifies the *local* development process with CI, such that local test
results should match the outcomes of Travis's builds more closely. This ensures that your pull request can be merged
seamlessly into ProbNum's codebase.

Install tox from the Python Package Index (PyPI) via
```bash
pip install -U tox
```
Once tox and the required [external tools](#external-tools) below are installed, you can run tests and build the documentation locally by simply calling
Once tox and the required [external tools](#external-tools) below are installed, you can run tests and build the
documentation locally by simply calling
```bash
tox
```

**Word of caution:**
Running `tox` runs all environments as specified in `tox.ini`, thus potentially running tests across many different python versions.
To run the full test suite make sure that you have all specified python versions installed.
Alternatively, you can run a single specific environment through `tox -e <env>`, e.g. `tox -e py36` to run tests with Python 3.6 or `tox -e docs` to just build the documentation.
Running `tox` runs all environments as specified in `tox.ini`, thus potentially running tests across many different
Python versions. To run the full test suite make sure that you have all specified Python versions installed.
Alternatively, you can run a single specific environment through `tox -e <env>`, e.g. `tox -e py36` to run tests with
Python 3.6 or `tox -e docs` to just build the documentation.

### External Tools

Building the documentation locally requires additional packages (e.g. for inheritance diagrams), which can be found in `.travis.yml`. These packages are currently:
Building the documentation locally requires additional packages (e.g. for inheritance diagrams), which can be found in
`.travis.yml`. These packages are currently:
- [pandoc](https://pandoc.org/): In Ubuntu, install via `sudo apt install pandoc`
- [graphviz](https://graphviz.org/): In Ubuntu, install via `sudo apt install graphviz`

## Testing

[![test coverage: latest](https://img.shields.io/codecov/c/gh/probabilistic-numerics/probnum/master?label=Coverage%3A%20latest&logo=codecov)](https://codecov.io/gh/probabilistic-numerics/probnum/branch/master)
[![test coverage: development](https://img.shields.io/codecov/c/gh/probabilistic-numerics/probnum/development?label=Coverage%3A%20dev&logo=codecov)](https://codecov.io/gh/probabilistic-numerics/probnum/branch/development)

We use [unittest](https://docs.python.org/3/library/unittest.html) for testing and aim to cover as much code with tests as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have multiple options:
We use [unittest](https://docs.python.org/3/library/unittest.html) for testing and aim to cover as much code with tests
as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have
multiple options:

- **Full test suite with tox:** Run the full suite across different Python versions with

Expand All @@ -81,20 +92,23 @@ We use [unittest](https://docs.python.org/3/library/unittest.html) for testing a
```bash
pytest
```
Code coverage of the tests is reported via [codecov](https://codecov.io/github/probabilistic-numerics/probnum?branch=master).

## Documentation

[![docs: stable](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20stable)](https://probnum.readthedocs.io/en/stable/)
[![docs: latest](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20latest)](https://probnum.readthedocs.io/en/latest/)
[![docs: development](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20dev&version=development)](https://probnum.readthedocs.io/en/development/)

ProbNum's documentation is created with [Sphinx](https://www.sphinx-doc.org/en/master/) and automatically built and hosted by [ReadTheDocs](https://readthedocs.org/projects/probnum/) for stable (release), latest (`master` branch) and dev (`development` branch) versions.
ProbNum's documentation is created with [Sphinx](https://www.sphinx-doc.org/en/master/) and automatically built and
hosted by [ReadTheDocs](https://readthedocs.org/projects/probnum/) for stable releases and the latest (`master` branch)
version.

You can build the documentation locally via
```bash
tox -e docs
```
This creates a static web page under `./docs/_build/html/` which you can view in your browser by opening `./docs/_build/html/intro.html`.
This creates a static web page under `./docs/_build/html/` which you can view in your browser by opening
`./docs/_build/html/intro.html`.

Alternatively, if you want to build the docs in your current environment you can manually execute
```bash
Expand All @@ -106,9 +120,11 @@ make html
## Continuous Integration

[![build status: latest](https://img.shields.io/travis/probabilistic-numerics/probnum/master.svg?logo=travis%20ci&logoColor=white&label=Travis%20CI:%20latest)](https://travis-ci.org/github/probabilistic-numerics/probnum/branches)
[![build status: development](https://img.shields.io/travis/probabilistic-numerics/probnum/development.svg?logo=travis%20ci&logoColor=white&label=Travis%20CI:%20dev)](https://travis-ci.org/github/probabilistic-numerics/probnum/branches)

ProbNum uses [Travis CI](https://travis-ci.org/probabilistic-numerics/probnum) for continuous integration.
For every pull request and every commit Travis builds the project and runs the test suite (through `tox`), to make sure that no breaking changes are introduced by mistake.
Code coverage of the tests is reported through [codecov](https://codecov.io/github/probabilistic-numerics/probnum?branch=master). Travis also automatically triggers a build of ProbNum's documentation. Changes to Travis can be made through the `.travis.yml` file, as well as through `tox.ini` since Travis relies on `tox` for both testing and building the documentation.
ProbNum also uses [GitHub Actions](https://docs.github.com/en/actions) to verify that all pushes and pull requests are compliant with the [*Black*](https://github.com/psf/black) code style.
For every pull request and every commit Travis builds the project and runs the test suite (through `tox`), to make sure
that no breaking changes are introduced by mistake. Travis also automatically triggers a
build of ProbNum's documentation. Changes to Travis can be made through the `.travis.yml` file, as well as through
`tox.ini` since Travis relies on `tox` for both testing and building the documentation. ProbNum also uses
[GitHub Actions](https://docs.github.com/en/actions) to verify that all pushes and pull requests are compliant with the
[*Black*](https://github.com/psf/black) code style.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ To get started install ProbNum using `pip`.
```bash
pip install probnum
```
Alternatively, you can install the package from source.
Alternatively, you can install the latest version from source.
```bash
pip install git+https://github.com/probabilistic-numerics/probnum.git
```
Expand Down
3 changes: 2 additions & 1 deletion docs/source/development/developer_guides.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
Developer Guides
=======================

Do you want to contribute to ProbNum, but are unsure how? The developer guides below give step-by-step instructions on how to contribute to the codebase via a pull request.
Do you want to contribute to ProbNum, but are unsure how? The developer guides below give step-by-step instructions on
how to contribute to the codebase via a pull request.

.. toctree::
:maxdepth: 1
Expand Down
11 changes: 9 additions & 2 deletions docs/source/development/documentation.rst
Original file line number Diff line number Diff line change
@@ -1,12 +1,19 @@
Adding to the Documentation
============================

Documentation is an integral part of every collaborative software project. Good documentation not only encourages users of the package to try out different functionalities, but it also makes maintaining and expanding code significantly easier. If you want to improve ProbNum's documentation or learn how to write documentation for your newly implemented functionality, keep reading.
Documentation is an integral part of every collaborative software project. Good documentation not only encourages users
of the package to try out different functionalities, but it also makes maintaining and expanding code significantly
easier. If you want to improve ProbNum's documentation or learn how to write documentation for your newly implemented
functionality, keep reading.

Docstrings
***********

The main form of documentation are `docstrings`, multi-line comments beneath a class or function definition with a specific syntax, which detail its functionality. This package uses the `NumPy docstring format <https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide>`_. As a rule, all functions which are exposed to the user *must* have appropriate docstrings. Below is an example of a docstring for a probabilistic numerical method.
The main form of documentation are `docstrings`, multi-line comments beneath a class or function definition with a
specific syntax, which detail its functionality. This package uses the
`NumPy docstring format <https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide>`_. As a rule,
all functions which are exposed to the user *must* have appropriate docstrings. Below is an example of a docstring for a
probabilistic numerical method.

.. code-block:: python
Expand Down
24 changes: 18 additions & 6 deletions docs/source/development/example_notebook.rst
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
Adding an Example Notebook
===========================

Functionality of ProbNum is explained in detail in the form of Jupyter notebooks in the `tutorials section <https://probnum.readthedocs.io/en/latest/development/developer_guides.html>`_ of the documentation. If you want to add an example showcasing the functionality of ProbNum, follow the instructions below.
Functionality of ProbNum is explained in detail in the form of Jupyter notebooks in the
`tutorials section <https://probnum.readthedocs.io/en/latest/development/developer_guides.html>`_ of the documentation.
If you want to add an example showcasing the functionality of ProbNum, follow the instructions below.

Creating the Notebook
**********************

We begin by creating a new Jupyter notebook under :code:`./docs/source/tutorials/`. If you want some guidance on the style, simply copy one of the existing notebooks. If you create your own ensure that the first cell is a markdown cell containing an upper level markdown header (:code:`# Header`) to be converted correctly to HTML.
We begin by creating a new Jupyter notebook under :code:`./docs/source/tutorials/`. If you want some guidance on the
style, simply copy one of the existing notebooks. If you create your own ensure that the first cell is a markdown cell
containing an upper level markdown header (:code:`# Header`) to be converted correctly to HTML.

In order to keep the style of the output consistent, the first code cell of the notebook should contain the following code snippet:
In order to keep the style of the output consistent, the first code cell of the notebook should contain the following
code snippet:

.. code-block:: python
Expand All @@ -26,13 +31,18 @@ In order to keep the style of the output consistent, the first code cell of the
r'\usepackage{bm}']
This snippet defines the style of plots generated by Matplotlib. For example it defines the font and makes sure any output is a vector graphic. If you need to use specific LaTeX packages, e.g. to label your plots, simply add them to the list :code:`plt.rcParams['text.latex.preamble']`.
This snippet defines the style of plots generated by Matplotlib. For example it defines the font and makes sure any
output is a vector graphic. If you need to use specific LaTeX packages, e.g. to label your plots, simply add them to the
list :code:`plt.rcParams['text.latex.preamble']`.


Adding the Notebook to the Website
***********************************

Now that you've created your notebook, we have to add it in the right place on the website. Check the existing categories in :code:`./docs/source/tutorials/tutorials.rst` and add your notebook name under the appropriate header. If you want to add a new category, use the following restructuredText snippet to add a new table of contents linking to your notebook:
Now that you've created your notebook, we have to add it in the right place on the website. Check the existing
categories in :code:`./docs/source/tutorials/tutorials.rst` and add your notebook name under the appropriate header. If
you want to add a new category, use the following restructuredText snippet to add a new table of contents linking to
your notebook:

.. code-block:: rst
Expand Down Expand Up @@ -78,6 +88,8 @@ If the notebook compiles successfully, you should see output similar to:
build succeeded.
You can now view your results locally by opening the website in :code:`./docs/_build/html`. Make sure you fix any error messages popping up in the build before making a pull request to the :code:`development` branch. Once your pull request has been merged, Travis will automatically build the documentation including your new example notebook.
You can now view your results locally by opening the website in :code:`./docs/_build/html`. Make sure you fix any error
messages popping up in the build before making a pull request to the :code:`master` branch. Once your pull request
has been merged, Travis will automatically build the documentation including your new example notebook.


15 changes: 8 additions & 7 deletions docs/source/development/probnum_method.rst
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
Implementing a Probabilistic Numerical Method
=============================================

Probabilistic numerical methods in ProbNum follow the dogma of having random variables as input and random variables as output. Hence their signature should be similar to
Probabilistic numerical methods in ProbNum follow the dogma of having random variables as input and random variables as
output. Hence their signature should be similar to

.. code-block:: python
randvar_out = probnum_method(problem, randvar_in, **kwargs)
where :code:`problem` defines the numerical problem to solve, :code:`randvar_in` is the input random variable encoding prior
information and :code:`**kwargs` are keyword arguments that influence the behaviour
where :code:`problem` defines the numerical problem to solve, :code:`randvar_in` is the input random variable encoding
prior information and :code:`**kwargs` are keyword arguments that influence the behaviour
of the solver (e.g. control termination). If your method has a classic analogue in NumPy or SciPy, make sure the
signatures match as closely as possible. This enables PN methods to be used as drop-in replacements for classic
numerical routines.
Expand Down Expand Up @@ -143,8 +144,8 @@ Testing
********

While or even before you add a new PN method, write tests for its functionality. Writing tests before the
code forces you to think about what your numerical method should do independent of its implementation. Some basic tests to consider are listed
below.
code forces you to think about what your numerical method should do independent of its implementation. Some basic tests
to consider are listed below.

In- and Output
"""""""""""""""
Expand All @@ -159,5 +160,5 @@ Numerical

Conclusion
***********
Once you are done, consider writing an `example notebook <https://probnum.readthedocs.io/tutorials/tutorials.html>`_ showcasing your new
method. Congratulations you just implemented your first probabilistic numerical method in ProbNum!
Once you are done, consider writing an `example notebook <https://probnum.readthedocs.io/tutorials/tutorials.html>`_
showcasing your new method. Congratulations you just implemented your first probabilistic numerical method in ProbNum!
Loading

0 comments on commit f0b94f0

Please sign in to comment.