search

AusDTO / apiguide

API Design Guide
http://apiguide.readthedocs.org/
Other
43 stars 32 forks source link

decouple document system from rest of DEV environment #7

Closed monkeypants closed 4 years ago

monkeypants commented 9 years ago

Right now, these docs build out fine on my DEV machine and in my CI environment, but there is probably unknown pain for future contributors to get a document build-out going like mine.

Should definitely move the Dockerfile into this repo and make sure it's cleanly separated from the rest of the DEV environment. Might also be good opportunity to clean up all the latex package dependencies, graphviz, etc. Make sure everything works comes up and works from a fresh install.

Rather than documenting our CI setup, it might be better to refactor the logic out of config and into a script that serves as a wrapper/documentation (so CI just runs the script, that's it).

monkeypants commented 9 years ago

Probably good to also update the README after this. Just saying...

markmuir87 commented 9 years ago

Might this just be a matter of syntax and logical organisation of the repo? So root level would just be a README.md file, with first-level folders separating the documentation content and config files? Whatever arrangement we settle on, I assume our guiding principle is to make it as easy as possible for others to collaboratively edit? (though small technical hurdles aren't too big a deal, given collaborators are likely to be of the technical sort...)

Edit: Forgot to ask, re-use isn't a consideration here right? It doesn't seem like anyone other than us will want to put this content into production. If there is a case for re-use, we should probably have a plain-text representation of the content, so that people don't have to parse out the MD when re-using.