haskell-numpy-docs
This repo provides the docs with which one can compare how use Haskell (and associated libraries) in the same way one would use the Python numerical library numpy. A contribution of the DataHaskell project.
The actual docs
https://pechersky.github.io/haskell-numpy-docs/
Structure
The numpy docs are provided as a submodule, pointing to the numpy repo.
The examples are in the src directory, grouped by the docs page that they are
associated with. Each docs page can have a different library provide examples.
Each library should get its own hs file. For example, there is a
src/quickstart/hmatrix.hs for the HMatrix version of the numpy
quickstart docs.
The actual docs pages are built using Sphinx, a Python
documentation generator. It uses an rst format. To write docs based on the
examples you wrote, use the sphinx-tabs and the specially
written comparetabs extensions. The docs rsts only require pointing to the
parent example documents, the lines that each example should pull in, and the
language of the example. For a good starting point, check out
docs/quickstart.rst.
Developing
Select the library you want to test. Add it to the haskell-numpy-docs.cabal
file. Run stack solver to prepare the dependencies. Run stack build to
provide install the libraries.
There are some special things you might need to do to develop on Windows
machines. Specifically, you need to provide a BLAS implementation for HMatrix to
work. Check out stack.yaml for an example.
Testing
You can write the Haskell examples to be valid Haskell. This is verifiable using
the doctest library. To check an examples file, run a command
like stack exec doctest src/quickstart/hmatrix.hs, for example.
Building documentation
Make sure the proper Python dependencies are installed using pip install -r requirements.txt. To build the documentation, cd to the docs directory. Run
make html.
For directions about how to push the docs, take a look at how to push docs.
Contributing
File a PR with a new library, or new examples, or more idiomatic Haskell code. File an issue for more in-depth discussion. Visit the DataHaskell channel and talk!
Advanced git stuff
Pushing docs
In a properly set up repo, following a make html, run:
cd _build/html
git commit -a -m 'new examples here'
git push origin gh-pages
This is based on a way to provide sphinx documentations to GitHub pages, given at https://gist.github.com/brantfaircloth/791759.
The simple explanation of how to set this up for you is that in the _build/html
directory, you need to
cd docs
git clone [email protected]:pechersky/haskell-numpy-docs.git _build/html
cd _build/html
git checkout master
rm .git/index
git clean -fdx
git checkout gh-pages
This is because the first part of the gist was already done. Be careful to not
push the docs to the master branch!
Yakov Pechersky, 2017