From 95a009e95d85858a89638ef61400cdabb5b082f3 Mon Sep 17 00:00:00 2001
From: davidovitch <david.verelst@gmail.com>
Date: Fri, 9 Dec 2016 09:30:44 +0100
Subject: [PATCH] docs: update dev-guide, add note on pypandoc and rst readme
 for pypi, fixes #25

---
 docs/developer-guide.md | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index a5b30e7..ed7dc43 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -206,11 +206,14 @@ The workflow to make a merge request is as follows:
 To be written
 
 
-## Make and upload wheels
+## Make and upload wheels to PyPi
 
-Using conda:
+Uploading wheels to [PyPi](https://pypi.python.org/pypi) is easy thanks to
+```[twine](https://pypi.python.org/pypi/twine)```.
+
+Install ```twine``` using conda:
 ```
->> conda install --channel https://conda.anaconda.org/pbrod twine --no-channel-priority
+>> conda install --channel https://conda.anaconda.org/pbrod twine --no-deps
 ```
 
 Or pip:
@@ -218,6 +221,25 @@ Or pip:
 >> pip install twine
 ```
 
+One additional complication with PyPi is that the package description is required
+to be in the ```rst``` format, while the ```wetb``` readme file is currently
+formatted in ```md```. To solve this,
+```[pypandoc](https://pypi.python.org/pypi/pypandoc)``` can be used to convert
+```README.md``` on the fly to ```rst```. A discussion on how this can be done
+is also recorded in issue #22.
+
+Install ```pypandoc``` using conda:
+```
+>> conda install pandoc
+```
+
+Or pip:
+```
+>> pip install pypandoc
+```
+
+Workflow for creating and uploading wheels is as follows:
+
 - Make tag: ```git tag "vX.Y.Z"```, and push tag to remote: ```git push --tags```
 - In order to have a clean version number (which is determined automagically)
 make sure your git working directory is clean (no uncommitted changes etc).
@@ -234,5 +256,5 @@ In case of problems:
 
 - Make sure the version tag is compliant with
 [PEP 440](https://www.python.org/dev/peps/pep-0440/), otherwise ```twine upload```
-will fail. This means commit hashes can not be part of a release version.
+will fail. This means commit hashes can not be part of the version number.
 
-- 
GitLab