bcwaldon / dev-center

Sust Global Dev Center

This is the home of Sust Global's developer tools, guides and reference documentation. The documentation maintained in this repository is hosted at https://developers.sustglobal.com/. Please start there and come back to this repository as needed to access interactive tools and assets.

Need help? Find a bug? Please file an issue and we'll get back to you.

Documentation

The documentation source in this repo is built and published to https://developers.sustglobal.com/. Please head to that URL if you only need to read the docs.

If you wish to contribute changes to the docs, please follow the guidance below.

Working with the Docs

The majority of local documentation is built using Jekyll (all markdown docs in ./jekyll/). Local development depends on having a proper Ruby environment set up. Documentation is available here: https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll.

Once you have ruby and bundler installed, you should be able to run the following from ./jekyll/ and see the documentation site up at http://localhost:4000:

bundle install && bundle exec jekyll serve

Note that jekyll reads from the ./jekyll directory, then places rendered files in ./docs. This means that you should NEVER edit files in ./docs by hand, as your changes will be overwritten.

Building and Publishing Docs

Since we rely on a nonstandard jekyll plugin, we actually have to build the site locally and check it in directy. Assuming you have a working dev environment (see above), you can just run the following and check in the result.

bundle exec jekyll build

The static files generated by jekyll end up in ./docs/, so be sure to include this when you commit your work. Open a PR to this repo containing your new commit(s), and the team will review and merge it.

Upon a merge to master, Github Pages will automatically pick up your changes and publish to https://developers.sustglobal.com/.

Python Client Docs

The python client docs are built using Sphinx. This tool automatically reads docstrings as well as some limited rst files, then renders styled HTML. Build these docs with the script in ./clients/:

./clients/tools/build-docs.sh

Generated documentation will bypass the jekyll toolchain and land directly into ./docs/py. Commit these changes directly to the repo and the static site will be deployed automatically.