Merge pull request #2 from cal-itp/docs

Publish docs via GitHub Pages

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,4 +1,4 @@
-----
+---
 name: Bug report
 about: Create a report to help us improve
 title: "[BUG] Description of problem"
@@ -8,26 +8,29 @@ assignees: ''
 ---
 
 ## Describe the bug
-A clear and concise description of what the bug is or the error code you got. e.g. 
-```python 
+
+A clear and concise description of what the bug is or the error code you got. e.g.
+
+```python
 KeyError: 'Passing list-likes to .loc or [] with any missing labels is no longer supported, see https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#deprecate-loc-reindex-listlike'
 ```
 
 ## To Reproduce
+
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
 ### Failing tests
+
 - [ ] No applicable test failed, need to create.
-- [ ] 
+- [ ]
 
 ### Triggering line of code
 
-
 ### Thoughts on resolution
 
 ### Full stack trace
-

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,25 +8,30 @@ assignees: ''
 ---
 
 ### User Story
+
 *As a ...insert type of user... I'd like to ...insert desired feature or behavior...*
 
-### Priority 
+### Priority
 
 ### Level of Effort
 
 ### Resolution Ideas
 
 ### Project
+
 *Is there a funder or project associated with this feature?*
 
 ### Who should be involved?
-Implementer: 
-Commenters: 
-Users: 
-Reviewers: 
+
+Implementer:
+Commenters:
+Users:
+Reviewers:
 
 ### Risk
+
 *Will this potentially break anything?*
 
 #### Tests
-*What are relevant tests or what tests need to be created in order to determine that this issue is complete?*
+
+*What are relevant tests or what tests need to be created in order to determine that this issue is complete?*

.github/pull_request_template.md

@@ -1,26 +1,27 @@
--## What existing problem does the pull request solve and why should we include it?
+# New Pull Request
 
+## What existing problem does the pull request solve and why should we include it?
 
 ## What is the testing plan?
 
-*Demonstrate the code is solid by discussing how results are verified and covered by tests*
+*Demonstrate the code is solid by discussing how results are verified and covered by tests.*
 
- - [ ] Code for this PR is covered in tests 
- - [ ] Code passes all existing tests
+- [ ] Code for this PR is covered in tests
+- [ ] Code passes all existing tests
 
 ## Code formatting
+
 *Code should be PEP8 compliant before merging by running a package like [`black`](https://pypi.org/project/black/)*
 
- - [ ] Code linted
+- [ ] Code linted
 
 ## Applicable Issues
+
 *Please do not create a Pull Request without creating an issue first.*
 
 *Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes.*
 
-
-#### Issues List
-
- -  closes...
- -  closes...
+### Issues List
 
+- closes...
+- closes...

.github/workflows/mkdocs.yml

@@ -0,0 +1,20 @@
+name: Publish docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  mkdocs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          REQUIREMENTS: dev-requirements.txt
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -1,9 +1,8 @@
 # Changelog
 
 ## Version 0.0.1 (2021-05-03)
-Initial version of TransitStack viewer capable of:
 
- - importing transit stack data from gsheet or local csvs
- - visualizing relationships using digrams package (graphviz)
+Initial version of TransitStack viewer capable of:
 
-
+- importing transit stack data from gsheet or local csvs
+- visualizing relationships using digrams package (graphviz)

README.md

@@ -2,7 +2,7 @@
 
 Basic tools for downloading and viewing the [Cal-ITP](http://calitp.org) transit technology stack database.
 
-![](/docs/stack_diagram_-_functional_view.png)
+![Example stack diagram](/docs/stack_diagram_-_functional_view.png)
 
 ## Installation
 
@@ -26,7 +26,8 @@ my_stack.components_df.products
 my_stack.components_df['products'].value_counts().sort_values(as‌​cending=False)
 ```
 
-You can use the Jupyter Notebook `/notebooks/Stack Database Analysis.ipynb` for interactive viewing of dataframes by using the command `jupyter notebook`. 
+You can use the Jupyter Notebook `/notebooks/Stack Database Analysis.ipynb` for interactive viewing of dataframes by using the
+command `jupyter notebook`.
 
 ### Browse relationships in Single Transit Stack
 
@@ -51,15 +52,16 @@ d = ts.stack_diagram(
     cluster_level_2 = LEVEL2,
     bgcolor_cluster_L1 = ts.stack.greenyellow_functiongroup_map,
 )
-
 ```
 
-You can use the Jupyter Notebook `/notebooks/Individual Transit Provider Analysis.ipynb` for interactive transit stack diagram generation by using the command `jupyter notebook`. 
+You can use the Jupyter Notebook `/notebooks/Individual Transit Provider Analysis.ipynb` for interactive transit stack diagram
+generation by using the command `jupyter notebook`.
 
 ## Contributing
 
-General steps: 
-1. Fork it (https://github.com/e-lo/Transitstacks/fork)
+General steps:
+
+1. Fork it (<https://github.com/e-lo/Transitstacks/fork>)
 2. Create your feature branch (`git checkout -b feature/fooBar`)
 3. Add your feature, add tests which test your feature, document your feature, and pass all tests.
 4. Commit your changes (`git commit -am 'Add some fooBar'`)
@@ -71,13 +73,14 @@ Development requirements are listed in `dev-requirements.txt` and can be install
 
 Tests are written for `pytest` and can be run using the command `pytest`.
 
-Docstrings are written in [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and auto-rendered as api documentation using [mkdocstrings](https://mkdocstrings.github.io/) as specified in `/docs/api.md`. 
-
-Documentation uses [mkdocs](https://www.mkdocs.org/) and is in the `/docs` folder.  It can be rendered locally using the command `mkdocs serve`. 
+Docstrings are written in [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and
+auto-rendered as api documentation using [mkdocstrings](https://mkdocstrings.github.io/) as specified in `/docs/api.md`.
 
+Documentation uses [mkdocs](https://www.mkdocs.org/) and is in the `/docs` folder.
+It can be rendered locally using the command `mkdocs serve`.
 
 ## Licenses
 
-- Code is offered as [AGPL 3.0](LICENSE) and developed on behalf of the [California Integrated Travel Project](http://calitp.org).  
-- Data is offered as [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) and developed on behalf of the [California Integrated Travel Project](http://calitp.org). 
-
+* Code is offered as [AGPL 3.0](LICENSE) and developed on behalf of the [California Integrated Travel Project](http://calitp.org).
+* Data is offered as [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) and developed on behalf of the
+  [California Integrated Travel Project](http://calitp.org).

docs/api.md

@@ -28,4 +28,4 @@
     handler: python
     rendering:
       show_root_heading: True
-      heading_level: 2
+      heading_level: 2

docs/developing.md

@@ -3,8 +3,8 @@
 ## Setting up environment
 
 ### Installation
-If you are going to be working on Transitstacks locally, you might want to clone it to your local machine and install it from the clone.  The -e will install it in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/?highlight=editable#editable-installs).
 
+If you are going to be working on Transitstacks locally, you might want to clone it to your local machine and install it from the clone. The -e will install it in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/?highlight=editable#editable-installs).
 
 ```bash
 conda config --add channels conda-forge
@@ -19,27 +19,33 @@ pip install -r dev-requirements.txt
 Notes:
 
 1. The -e installs it in editable mode.
-2. If you are not part of the project team and want to contribute code bxack to the project, please fork before you clone and then add the original repository to your upstream origin list per [these directions on github](https://help.github.com/en/articles/fork-a-repo).
+2. If you are not part of the project team and want to contribute code bxack to the project, please fork before you clone and
+   then add the original repository to your upstream origin list per
+   [these directions on github](https://help.github.com/en/articles/fork-a-repo).
 3. if you wanted to install from a specific tag/version number or branch, replace `@main` with `@<branchname>`  or `@tag`
-4. If you want to make use of frequent developer updates for network wrangler as well, you can also install it from clone by copying the instructions for cloning and installing Lasso for Network Wrangler
+4. If you want to make use of frequent developer updates for network wrangler as well, you can also install it from clone by
+   copying the instructions for cloning and installing Lasso for Network Wrangler
 
 ### Other tools
+
 If you are going to be doing development, we also recommend a few other tools:
- -  a good IDE such as [VS Code](https://code.visualstudio.com/), Sublime Text, etc.
- with Python syntax highlighting turned on.
- - [GitHub Desktop](https://desktop.github.com/) to locally update your clones
+
+- a good IDE such as [VS Code](https://code.visualstudio.com/), Sublime Text, etc. with Python syntax highlighting turned on.
+- [GitHub Desktop](https://desktop.github.com/) to locally update your clones
 
 ## Development Workflow
 
-General steps: 
-1. Fork it (https://github.com/e-lo/Transitstacks/fork)
+General steps:
+
+1. Fork it (<https://github.com/e-lo/Transitstacks/fork>)
 2. Create your feature branch (`git checkout -b feature/fooBar`)
 3. Add your feature, add tests which test your feature, document your feature, and pass all tests.
 4. Commit your changes (`git commit -am 'Add some fooBar'`)
 5. Push to the branch (`git push origin feature/fooBar`)
 6. Create a new Pull Request
 
 ## Tests
+
 Tests are written for `pytest` and can be run using the command `pytest`.
 
 Tests are run with the [pyTest](pytest.org)/
@@ -53,58 +59,72 @@ Tests are run with the [pyTest](pytest.org)/
 Pytest can be installed using one of the following options.
 
 Install along with all development requirements (recommended):
-```sh
+
+```bash
 pip install -r dev-requirements.txt
 ```
-Install using PIP: 
-```sh
+
+Install using PIP:
+
+```bash
 pip install pytest
 ```
-Install using Conda: 
-```sh
+
+Install using Conda:
+
+```bash
 conda install pytest
 ```
 
 ### Running tests
 
 1. Run all tests
-```sh
-pytest 
-```
+
+    ```bash
+    pytest
+    ```
 
 2. Run tests in `test_basic.py`
-```sh
-pytest tests/test_basic.py
-```
+
+   ```bash
+   pytest tests/test_basic.py
+   ```
 
 3. Run tests decorated with @pytest.mark.favorites decorator
-```sh
-pytest -m favorites
-```
+
+   ```bash
+   pytest -m favorites
+   ```
 
 4. Run all tests and print out stdout
-```sh
-pytest -s
-```
+
+   ```bash
+   pytest -s
+   ```
 
 5. Run all tests which are run on the CI server
-```sh
-pytest -v -m "not skipci"
-```
+
+   ```bash
+   pytest -v -m "not skipci"
+   ```
 
 ## Continuous Integration
 
 Transitstacks uses Github workflows to run tests for each push to the repository as configured in `.github/workflows`
 
 ### Troubleshooting Github Actions
 
-Sometimes it is useful to trubleshoot github actions locally. The easiest way to do that is to install [`act`](https://github.com/nektos/act) (e.g. `brew install act` on Mac OS) and run it from the command line from the base transit stacks repository using the straightforward command: `act`. 
+Sometimes it is useful to trubleshoot github actions locally. The easiest way to do that is to install
+[`act`](https://github.com/nektos/act) (e.g. `brew install act` on Mac OS) and run it from the command line from the base
+Transitstacks repository using the straightforward command: `act`.
 
 ## Documentation
-Docstrings are written in [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and auto-rendered as api documentation using [mkdocstrings](https://mkdocstrings.github.io/) as specified in `/docs/api.md`. 
 
-Documentation uses [mkdocs](https://www.mkdocs.org/) and is in the `/docs` folder.  It can be rendered locally using the command `mkdocs serve`. 
+Docstrings are written in [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and
+auto-rendered as api documentation using [mkdocstrings](https://mkdocstrings.github.io/) as specified in `/docs/api.md`.
 
+Documentation uses [mkdocs](https://www.mkdocs.org/) and is in the `/docs` folder. It can be rendered locally using the
+command `mkdocs serve`.
 
-**Reminder**
-This code is offered with the [AGPL 3.0](LICENSE) license and developed on behalf of the [California Integrated Travel Project](http://calitp.org), which is **share-alike**. 
+**Reminder:** This code is offered with the [AGPL 3.0](LICENSE) license and developed on behalf of the
+[California Integrated Travel Project](http://calitp.org), which is **share-alike**.

docs/index.md

@@ -1,9 +1,12 @@
-Transitstacks includes basic tools for downloading and viewing the [Cal-ITP](http://calitp.org) transit technology stack database including generating stack diagrams the example one below. 
+# Transitstacks
 
-![](stack_diagram_-_functional_view.png)
+Transitstacks includes basic tools for downloading and viewing the [Cal-ITP](http://calitp.org) transit technology stack
+database including generating stack diagrams the example one below.
 
-## Licenses
+![Example stack diagram](stack_diagram_-_functional_view.png)
 
-- Code is offered as [AGPL 3.0](LICENSE) and developed on behalf of the [California Integrated Travel Project](http://calitp.org).  
-- Data this code accesses and contains is offered as [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) and developed on behalf of the [California Integrated Travel Project](http://calitp.org). 
+## Licenses
 
+- Code is offered as [AGPL 3.0](LICENSE) and developed on behalf of the [California Integrated Travel Project](http://calitp.org).
+- Data this code accesses and contains is offered as [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) and
+  developed on behalf of the [California Integrated Travel Project](http://calitp.org).