search

LSSTDESC / ComputingInfrastructure

Gathering place for CI - Computing and Infrastructure - issues
3 stars 1 forks source link

Issue/13/migrate doc from confluence #15

Closed heather999 closed 8 years ago

heather999 commented 8 years ago

Here is a first stab at converting the Confluence page: https://confluence.slac.stanford.edu/display/LSSTDESC/Developing+DESC+Software to reStructuredText. Seems very similar to Markdown. After some more inquiries via community.lsst.org, I saw DM is also using Pandoc (pandoc.org) to handle automatic conversion of their pre-existing documentation. Installed it on my Mac, and exported the Confluence page to HTML. Pandoc did a reasonable first draft of conversion, but I did play around and edit the result further using GitHub's in-browser editor. There's more to learn about the syntax, but I'm getting the hang of it :) DM has a set of guidelines for reStructuredText: http://developer.lsst.io/en/latest/docs/rst_styleguide.html This Markdown vs. reStructuredText debate seems to be common: https://gist.github.com/dupuy/1855764 I don't have a good answer... except to say that Markdown & rST are similar. It may be worthwhile to follow in DM's footsteps as well as have the option to use some of reStructuredText's features.

heather999 commented 8 years ago

I was testing the links in the doc, the link here seem to be broken:

Using linters and static analysis tools to find and fix syntax and other low-level errors before the review frees the code reviewer to concentrate on more substantive aspects like algorithms and design.

which points to: http://astromemes.tumblr.com/post/51741245212

drphilmarshall commented 8 years ago

Hmm. I'll ask the astromemes manager what's going on!

Thanks for doing the conversion Heather! It looks good to me. @jchiang87 you should merge this if you're happy with it!

On Wed, Mar 23, 2016 at 7:17 AM, heather999 notifications@github.com wrote:

I was testing the links in the doc, the link here seem to be broken:

Using linters and static analysis tools to find and fix syntax and other low-level errors before the review frees the code reviewer to concentrate on more substantive aspects like algorithms and design.

which points to: http://astromemes.tumblr.com/post/51741245212

— You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub https://github.com/DarkEnergyScienceCollaboration/ComputingInfrastructure/pull/15#issuecomment-200363540

jchiang87 commented 8 years ago

I tweaked the formatting in a couple places. Otherwise, everything looked good. Thanks Heather!