How to Edit¶
Arc-docs is a set of documentation that is built and hosted on ReadTheDocs. ReadTheDocs is a service builds the documentation from a git repository whenever it receives a webhook event which is fired every time a new commit is made to that repo. The Arc-Docs repo is hosted on github: https://github.com/PSU-OIT-ARC/arc-docs
The easiest way to edit Arc-Docs is by navigating to the page you want to make a change to, then click the Edit on Github button in the top right corner of the page. This will take you to that files page on the github repo which will allow you to edit it in the browser.
Most changes can be made directly to the shared repo in the PSU-OIT-ARC organization, but you are free to use the fork, modify pull request pattern if you wish for larger changes or changes you want feedback on.
ReadTheDocs and Sphinx¶
ReadTheDocs fully supports the Sphinx documentation tool, which has quickly become the standard tool for documenting python projects. Sphinx is a superset of reStructuredText which is largely a superset of Markdown. It tends to be a bit more strict syntactically, but allows for much greater control over complex references and included codeblocks.
Useful RST References¶
- reStructuredText Primer
- sublime-text-unofficial-documentation privides a nice model layout of RTD documents.
RST Tools¶
It benefits from a well configured technical text editor such as vim, emacs, or Sublime Text.