Merge pull request #9 from sommersoft/new_docs

Improve Ref Docs

Author: kattni

readthedocs.yml renamed to .readthedocs.yml

@@ -16,15 +16,17 @@ deploy:
   provider: releases
   api_key: $GITHUB_TOKEN
   file_glob: true
-  file: bundles/*
+  file: $TRAVIS_BUILD_DIR/bundles/*
   skip_cleanup: true
+  overwrite: true
   on:
     tags: true
 
 install:
-  - pip install pylint circuitpython-build-tools
+  - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
 
 script:
   - pylint adafruit_mcp9808.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-mcp9808 --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

.travis.yml

@@ -16,10 +16,14 @@ over I2C. Its available on `Adafruit as a breakout <https://www.adafruit.com/pro
 
 Dependencies
 =============
+This driver depends on:
 
-This driver depends on the `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
-library. Please ensure it is also available on the CircuitPython filesystem. This is easily achieved by downloading
-`a library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 
 Usage Notes
 ===========
@@ -46,10 +50,56 @@ Then, construct the thermometer class:
       # Finally, read the temperature property and print it out
       print(t.temperature)
 
-API Reference
-=============
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_mcp9808/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Building locally
+================
+
+To build this library locally you'll need to install the
+`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install circuitpython-build-tools
+
+Once installed, make sure you are in the virtual environment:
+
+.. code-block:: shell
+
+    source .env/bin/activate
+
+Then run the build:
+
+.. code-block:: shell
+
+    circuitpython-build-bundles --filename_prefix adafruit-circuitpython-mcp9808 --library_location .
+
+Sphinx documentation
+-----------------------
+
+Sphinx is used to build the documentation based on rST files and comments in the code. First,
+install dependencies (feel free to reuse the virtual environment from above):
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install Sphinx sphinx-rtd-theme
+
+Now, once you have the virtual environment activated:
+
+.. code-block:: shell
 
-.. toctree::
-   :maxdepth: 2
+    cd docs
+    sphinx-build -E -W -b html . _build/html
 
-   api
+This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
+view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
+locally verify it will pass.