search

CityofSantaMonica / mds-provider

Python tools for working with MDS Provider data
https://github.com/openmobilityfoundation/mobility-data-specification
MIT License
18 stars 20 forks source link

Initial docs #21

Open hunterowens opened 5 years ago

hunterowens commented 5 years ago

MDS Provider deserves some docs.

This PR creates a docs directory, where you can place .md or .rst files to generate documentation. You can then serve it on the web using github pages.

The structure is as follows. 

├── Makefile
├── conf.py
├── index.rst
└── validate.md

Use make build to build html docs. conf.py defines some settings.

Additionally, this PR adds a Pipfile with just dev dependencies.

thekaveman commented 5 years ago

@hunterowens this is really cool! I was finally able to get make to work on Windows, and build and view these docs as HTML.

I've setup GitHub pages for static HTML and Jekyll sites, but not for something like this with custom build commands. I found this write-up of a possible flow but it doesn't get in to automation.

Do you have experience with that? Would CircleCI or Travis or something be able to help here?

@allejo maybe you've setup a python project with GH pages docs that build on commit/PR, or something similar?

thekaveman commented 5 years ago

I see that Sphinx also includes an extension githubpages but I'm not sure if/how this helps.

thekaveman commented 5 years ago

haha...

https://mds-provider.readthedocs.io/en/init-docs/

hunterowens commented 5 years ago

@thekaveman read the docs is your friend. I'll add a link in the README

hunterowens commented 5 years ago

Also re: make on windows, you can install a ubuntu VM from the windows store now, which is how I use ssh, make and other tools on my work computer.

thekaveman commented 5 years ago

rebased on master

thekaveman commented 5 years ago

Rebased on the forthcoming release in mds-0.3.

Added a small Docker setup for building and serving docs locally in a known environment.