Merge pull request #115 from Kai-Striega/doc/building-with-spin

Doc/building with spin

Author: Kai-Striega

doc/source/dev/building_the_docs.md

@@ -1,41 +1,30 @@
 # Building the docs
 
-This guide goes through how to build the NumPy-Financial documentation with poetry
+This guide goes through how to build the NumPy-Financial documentation with spin and conda
 
 ## Assumptions
 
 This guide assumes that you have set up poetry and a virtual environment. If you have 
-not done this please read [building_with_poetry](building_with_poetry.md).
+not done this please read [building_with_spin](building_with_spin).
 
-You can check that poetry is installed by running:
+You can check that conda and spin are installed by running:
 
 ```shell
-poetry -V
+conda -V
 ```
 
-## Installing the documentation dependencies
-
-NumPy-Financial is built using [sphinx](https://www.sphinx-doc.org/en/master/) with [numpydoc](https://numpydoc.readthedocs.io/en/latest/).
-
-The dependencies can be installed using poetry and the ``docs`` group:
-
 ```shell
-poetry install --with docs
+spin -V
 ```
 
 ## Building the documentation
 
-The documentation is located in the ``doc``  directory. The first step is to change directory into this directory
-
-```shell
-cd doc
-```
-
-Once you are in the ``doc`` directory, the documentation can be built using ``make``.
+spin handles building the documentation for us. All we have to do is invoke the built-in command.
 
 ```shell
-poetry run make html
+spin docs -j 1
 ```
 
-This will create the docs as a html document in the ``build`` directory. Note that there are several options available,
-however, only the html documentation is built officially.
+This will create the docs as a html document in the ``doc/build`` directory. Note that there are several options 
+available, however, only the html documentation is built officially.
+  

doc/source/dev/building_with_poetry.md

@@ -0,0 +1,63 @@
+# Building with spin and conda
+
+## Installing conda
+numpy-financial uses [spin](https://github.com/scientific-python/spin) and conda 
+to manage dependencies, build wheels and sdists, and publish to PyPI this page 
+documents how to work with spin and conda.
+
+To install poetry follow their [official guide](https://docs.anaconda.com/free/miniconda/miniconda-install/)
+it is recommended to use the official installer for local development.
+
+To check your installation try to check the version of miniconda:
+
+```shell
+conda -V
+```
+
+## Setting up a virtual environment using conda
+
+Once conda is installed it is time to set up the virtual environment. To do
+this run:
+
+```shell
+conda env create -f environment.yml
+```
+
+This command looks for dependencies in the ``environment.yml`` file,
+resolves them to the most recent version and installs the dependencies
+in a virtual environment. It is now possible to launch an interactive REPL
+by running the following command:
+
+```shell
+conda activate numpy-financial-dev
+```
+
+## Building NumPy-Financial
+
+NumPy-Financial is built using a combination of Python and Cython. We therefore
+require a build step. This can be run using
+
+```shell
+spin build
+```
+
+## Running the test suite
+
+NumPy-Financial has an extensive test suite, which can be run with the
+following command:
+
+```shell
+spin test
+```
+
+## Building distributions
+
+It is possible to manually build distributions for numpy-financial using
+poetry. This is possible via the `build` command:
+
+```shell
+spin build
+```
+
+The `build` command creates a `dist` directory containing a wheel and sdist
+file.

doc/source/dev/building_with_spin.md

@@ -5,8 +5,10 @@ Development
    :maxdepth: 1
 
    getting_the_code.md
-   building_with_poetry.md
+   building_with_spin.md
    running_the_benchmarks.md
+   building_the_docs.md
+   checking_out_an_upstream_pr.md
 
 
 .. include:: ../_includes/release-notes.rst