From 264c9f08ee9a89cd792b1e687e29d882afbede3d Mon Sep 17 00:00:00 2001 From: Pierre-Luc St-Charles Date: Thu, 18 Oct 2018 13:40:38 -0400 Subject: [PATCH] Update doc for next version bump --- CHANGELOG.rst | 8 ++++++++ CONTRIBUTING.rst | 27 ++++++++------------------- DOCUMENTATION.rst | 12 ++++++++++++ INSTALL.rst | 14 ++++---------- README.rst | 36 +++--------------------------------- docs/src/documentation.rst | 1 + docs/src/index.rst | 4 +--- docs/src/usage.rst | 5 ++--- 8 files changed, 39 insertions(+), 68 deletions(-) create mode 100644 DOCUMENTATION.rst create mode 100644 docs/src/documentation.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e6db195..299ffcd 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,3 +6,11 @@ Changelog ------------------- * Initial release (work in progress). + + +0.0.2 (2018/10/18) +------------------- + +* Completed first documentation pass. +* Fixed travis/rtfd builds. +* Fixed device mapping/loading issues. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 505e5aa..aaf4e9f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -40,23 +40,23 @@ To set up `thelper` for local development: (look for the "Fork" button). 2. Clone your fork locally:: - git clone git@github.com:your_name_here/thelper.git + $ git clone git@github.com:your_name_here/thelper.git 3. Create a branch for local development:: - git checkout -b name-of-your-bugfix-or-feature + $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. -4. When you're done making changes, run all the checks and doc builder with `tox `_ one command:: +4. When you're done making changes, run all the checks and doc builder with `tox `_ via:: - tox + $ make test-all 5. Commit your changes and push your branch to GitHub:: - git add . - git commit -m "Your detailed description of your changes." - git push origin name-of-your-bugfix-or-feature + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature 6. Submit a pull request through the GitHub website. @@ -67,7 +67,7 @@ If you need some code review or feedback while you're developing the code just m For merging, you should: -1. Include passing tests (run ``tox``) [1]_. +1. Make sure all tests are passing (run ``make test-all``) [1]_. 2. Update documentation when there's new API, functionality etc. 3. Add a note to ``CHANGELOG.rst`` about the changes. 4. Add yourself to ``AUTHORS.rst``. @@ -76,14 +76,3 @@ For merging, you should: `run the tests `_ for each change you add in the pull request. It will be slower though ... - -Tips ----- - -To run a subset of tests:: - - tox -e envname -- pytest -k test_myfeature - -To run all the test environments in *parallel* (you need to ``pip install detox``):: - - detox diff --git a/DOCUMENTATION.rst b/DOCUMENTATION.rst new file mode 100644 index 0000000..1320918 --- /dev/null +++ b/DOCUMENTATION.rst @@ -0,0 +1,12 @@ +============= +Documentation +============= + +The sphinx documentation is generated automatically via `readthedocs.io `_, but it might +still be incomplete due to buggy apidoc usage/platform limitations. To build it yourself, use the makefile:: + + $ cd + $ make docs + +The HTML documentation should then be generated inside ``/docs/build/html``. To browse it, simply open the +``index.html`` file there. diff --git a/INSTALL.rst b/INSTALL.rst index bd6e824..37ce0ee 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -12,7 +12,7 @@ the thelper framework and all its dependencies. In your terminal, simply enter:: $ make install If you already have conda installed somewhere, you can force the Makefile to use it for the installation of the -new environment by setting the :code:`CONDA_HOME` variable before calling make:: +new environment by setting the ``CONDA_HOME`` variable before calling make:: $ export CONDA_HOME=/some/path/to/miniconda3 $ cd @@ -31,8 +31,9 @@ Other systems ------------- If you cannot use the Makefile, you will have to install the dependencies yourself. These dependencies are listed in -the `requirements file `_, and can be installed using the conda environment configuration -file provided `here `_. For the latter case, call the following from your terminal:: +the `requirements file `_, and can also be installed +using the conda environment configuration file provided `here `_. +For the latter case, call the following from your terminal:: $ conda env create --file /conda-env.yml -n thelper @@ -61,10 +62,3 @@ that all dependencies can be loaded at runtime:: >>> import thelper >>> print(thelper.__version__) x.y.z - - -User guide ----------- - -For now, we offer some high-level guidelines in the `thelper_usage.txt `_ file contained in this -repository. More documentation will soon be added! diff --git a/README.rst b/README.rst index c41a2c4..dc3fbc7 100644 --- a/README.rst +++ b/README.rst @@ -56,39 +56,9 @@ This package provides a training framework and CLI for PyTorch-based machine lea under the `Apache Software License version 2.0 `_ built by researchers and developers from the Centre de Recherche Informatique de Montréal / Computer Research Institute of Montreal (CRIM). -For installation and usage instructions, refer to the `installation guide `_. - - -.. doc/dev instructions below not ready for live version (WiP) - - Documentation - ============= - - https://thelper.readthedocs.io/ - - Development - =========== - - To run the all tests run:: - - tox - - Note, to combine the coverage data from all the tox environments run: - - .. list-table:: - :widths: 10 90 - :stub-columns: 1 - - - - Windows - - :: - - set PYTEST_ADDOPTS=--cov-append - tox - - - - Other - - :: - - PYTEST_ADDOPTS=--cov-append tox +For installation instructions, refer to the `installation guide `_. For +usage instructions, refer to the `user guide `_. Information about +the auto-generated documentation is available `here `_. ===== Notes diff --git a/docs/src/documentation.rst b/docs/src/documentation.rst new file mode 100644 index 0000000..9ba590e --- /dev/null +++ b/docs/src/documentation.rst @@ -0,0 +1 @@ +.. include:: ../../DOCUMENTATION.rst diff --git a/docs/src/index.rst b/docs/src/index.rst index 0ebd46a..9d30bdf 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -7,6 +7,7 @@ Contents readme installation + documentation usage modules contributing @@ -16,7 +17,4 @@ Contents Indices and tables ================== -* :ref:`genindex` -* :ref:`modindex` * :ref:`search` - diff --git a/docs/src/usage.rst b/docs/src/usage.rst index 3f8009f..b05516c 100644 --- a/docs/src/usage.rst +++ b/docs/src/usage.rst @@ -2,6 +2,5 @@ Usage ===== -To use ``thelper`` in a project:: - - import thelper +For now, we offer some high-level guidelines in the `thelper_usage.txt `_ +file. More examples/tutorials will soon be added!