Merge pull request #64 from UDST/doc-cleanup

More documentation

CONTRIBUTING.md

@@ -1,55 +1,94 @@
-Thanks for using ChoiceModels! This is an open source project that's part of the Urban Data Science Toolkit. Development and maintenance is a collaboration between UrbanSim Inc and U.C. Berkeley's Urban Analytics Lab. You can contact Sam Maurer, the lead developer, at `maurer@urbansim.com`.
+Thanks for using ChoiceModels! 
 
-### If you encounter an error or find a bug:
+This is an open source project that's part of the Urban Data Science Toolkit. Development and maintenance is a collaboration between UrbanSim Inc and U.C. Berkeley's Urban Analytics Lab. 
 
-- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a discussion of the problem
+You can contact Sam Maurer, the lead developer, at `maurer@urbansim.com`.
 
-- Open a new issue describing the problem: circumstances, error messages, operating system you are using, version of python, and version of any libraries that may be relevant
 
-### If you have a feature proposal:
+## If you have a problem:
 
-- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a discussion of the topic
+- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a related discussion
+
+- Open a new issue describing the problem -- if possible, include any error messages, the operating system and version of python you're using, and versions of any libraries that may be relevant
+
+
+## Feature proposals:
+
+- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a related discussion
 
 - Post your proposal as a new issue, so we can discuss it (some proposals may not be a good fit for the project)
 
-### Adding a feature or fixing a bug:
 
-- Create a new branch of UDST/choicemodels, or fork the repository to your own account
+## Contributing code:
+
+- Create a new branch of `UDST/choicemodels`, or fork the repository to your own account
+
+- Make your changes, following the existing styles for code and inline documentation
 
-- Make your changes, adhering to the existing styles for coding, commenting, and especially the documentation strings at the beginning of functions
+- Add [tests](https://github.com/UDST/choicemodels/tree/master/tests) if possible!
 
-- Add [tests](https://github.com/UDST/choicemodels/tree/master/tests) if possible
+- Open a pull request to the `UDST/choicemodels` master branch, including a writeup of your changes -- take a look at some of the closed PR's for examples
 
-- When you're ready to begin code review, open a pull request to the UDST/choicemodels master branch
+- Current maintainers will review the code, suggest changes, and hopefully merge it!
 
-- The pull request writeup should be clear and thorough, to facilitate code review, documentation, and release notes (see [example here](https://github.com/UDST/choicemodels/pull/43)). First, briefly summarize the changes, referencing any associated issue threads. Then describe the changes in more detail: implementation, usage, performance, and anything else that's relevant
 
-- Make note in the pull request writeup of any API changes (class/method/function names, parameters, and behavior), particularly changes that could affect users' existing code
+## Updating the version number:
 
-- Each substantial pull request should increment the development version number, e.g. from 0.2.dev7 to 0.2.dev8
+- Each pull request that changes substantive code should increment the development version number, e.g. from `0.2.dev7` to `0.2.dev8`, so that users know exactly which version they're running
 
-- If incrementing the version number: (1) update `setup.py`, (2) update `choicemodels/__init__.py`, (3) add a section to `CHANGELOG.md`, and (4) add the version number to the beginning of the pull request name
+- It works best to do this just before merging (in case other PR's are merged first, and so you know the release date for the changelog and documentation)
 
-### Preparing a production release:
+- There are three places where the version number needs to be changed: 
+  - `setup.py`
+  - `choicemodels/__init__.py`
+  - `docs/source/index.rst`
 
-- Create a branch for release prep
+- Please also add a section to `CHANGELOG.md` describing the changes!
 
-- Make sure all the tests are passing
 
-- Update the version number (e.g. from 0.2.dev8 to 0.2) in `setup.py` and `choicemodels/__init__.py`
+## Updating the documentation: 
 
-- Update `CHANGELOG.md`, collapsing development release sections into a single, reorganized list
+- See instructions in `docs/README.md`
 
-- Check if updates are needed to `README.md` and to the documentation source files
 
-- Rebuild the documentation webpages (DETAILS TK)
+## Preparing a production release:
 
-- Open a pull request to the master branch
+- Make a new branch for release prep
 
-- Merge the pull request
+- Update the version number and `CHANGELOG.md`
+
+- Make sure all the tests are passing, and check if updates are needed to `README.md` or to the documentation
+
+- Open a pull request to the master branch and merge it
 
 - Tag the release on Github
 
-- Update the Python Package Index (DETAILS TK)
 
-- Update the UDST Conda channel (DETAILS TK)
+## Distributing a release on PyPI (for pip installation):
+
+- Register an account at https://pypi.org, ask one of the current maintainers to add you to the project, and `pip install twine`
+
+- Run `python setup.py sdist bdist_wheel --universal`
+
+- This should create a `dist` directory containing two package files -- delete any old ones before the next step
+
+- Run `twine upload dist/*` -- this will prompt you for your pypi.org credentials
+
+- Check https://pypi.org/project/choicemodels/ for the new version
+
+
+## Distributing a release on Conda Forge (for conda installation):
+
+- Make a fork of the [conda-forge/choicemodels-feedstock](https://github.com/conda-forge/choicemodels-feedstock) repository -- there may already be a fork in udst
+
+- Edit `recipe/meta.yaml`: 
+  - update the version number
+  - paste a new hash matching the tar.gz file that was uploaded to pypi (it's available on the pypi.org project page)
+
+- Check that the run requirements still match `requirements.txt`
+
+- Open a pull request to the `conda-forge/choicemodels-feedstock` master branch
+
+- Automated tests will run, and after they pass one of the current project maintainers will be able to merge the PR -- you can add your Github user name to the maintainers list in `meta.yaml` for the next update
+
+- Check https://anaconda.org/conda-forge/choicemodels for the new version (may take a few minutes for it to appear)

README.md

@@ -4,7 +4,7 @@
 
 # ChoiceModels
 
-ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the [Urban Data Science Toolkit](https://github.com/udst>) (UDST).
+ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the [Urban Data Science Toolkit](https://docs.udst.org) (UDST).
 
 
 ### Features
@@ -27,7 +27,7 @@ pip install choicemodels
 ```
 
 ```
-conda install choicemodels --channel udst
+conda install choicemodels --channel conda-forge
 ```
 
 

docs/README.md

@@ -0,0 +1,29 @@
+This folder generates the ChoiceModels online documentation, hosted at https://choicemodels.readthedocs.io and https://docs.udst.org.
+
+
+### How it works
+
+Read the Docs builds and hosts the Sphinx pages defined in `docs/source/`. Builds are triggered when the master branch of this Github repo changes.
+
+
+### Updating the documentation
+
+The pages are built using the Sphinx documentation generator. Here's a [good tutorial](https://pythonhosted.org/an_example_pypi_project/sphinx.html). Edit the `.rst` files and `conf.py` to change what appears in the rendered documentation.
+
+
+### Previewing changes locally
+
+Install `sphinx` and `sphinx_rtd_theme`.
+
+From the `docs` directory, run `sphinx-build -b html source build` to build the documentation. HTML files will show up in `docs/build/`.
+
+The build files won't be committed to the repo; Read the Docs will create a separate copy when the master branch is updated.
+
+
+### Hosting and troubleshooting
+
+Hosting settings are at https://readthedocs.org/projects/choicemodels/. If you don't have access, create a Read the Docs account and ask one of the existing maintainers to add you.
+
+The DNS settings for the docs.udst.org subdomain contain a CNAME record redirecting traffic to readthedocs.io. Read the Docs handles the SSL certificate for https. 
+
+The docs.udst.org landing page is generated by the `UDST/udst-docs` repository, with hosting settings at https://readthedocs.org/projects/udst-docs/. 

docs/source/getting-started.rst

@@ -4,7 +4,7 @@ Getting started
 Intro
 -----
 
-ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://github.com/udst>`__ (UDST).
+ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://docs.udst.org>`__ (UDST).
 
 The library currently focuses on tools to help integrate discrete choice models into larger workflows, drawing on other packages such as the excellent `PyLogit <https://github.com/timothyb0912/pylogit>`__ for most estimation of models. ChoiceModels can automate the creation of choice tables for estimation or simulation, using uniform or weighted random sampling of alternatives, as well as interaction terms or cartesian merges. It also provides general-purpose tools for Monte Carlo simulation of choices given probability distributions from fitted models, with fast algorithms for independent or capacity-constrained choices. ChoiceModels includes a custom engine for Multinomial Logit estimation that's optimized for fast performance with large numbers of alternatives.
 
@@ -30,9 +30,8 @@ ChoiceModels can be installed using the Pip or Conda package managers. We recomm
 
 .. code-block:: python
 
-    conda install choicemodels --channel udst
+    conda install choicemodels --channel conda-forge
 
-Using Conda, ChoiceModels is available on the ``udst`` channel immediately and on the ``conda-forge`` channel a few days after release.
 
 When new production releases of ChoiceModels come out, you can upgrade like this:
 
@@ -42,7 +41,7 @@ When new production releases of ChoiceModels come out, you can upgrade like this
 
 .. code-block:: python
 
-    conda update choicemodels --channel udst
+    conda update choicemodels --channel conda-forge
 
 
 Developer pre-releases
@@ -60,7 +59,7 @@ You can use the same command to upgrade.
 Cloning the repository
 ~~~~~~~~~~~~~~~~~~~~~~
 
-If you'll be modifying the code, you can install ChoiceModels by cloning the Github repository:
+You can also install ChoiceModels by cloning the Github repository, which is the best way to do it if you'll be modifying the code. The main branch contains the latest developer release. 
 
 .. code-block:: python
 

docs/source/index.rst

@@ -6,7 +6,7 @@
 ChoiceModels
 ============
 
-ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://github.com/udst>`__ (UDST).
+ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://docs.udst.org>`__ (UDST).
 
 v0.2.1, released January 30, 2019
 

tests/README.md

@@ -0,0 +1 @@
+Run tests from this folder using `pytest *.py -s`.