@jsick This is really great… I’m starting to look at reStructuredText for the Twinkles work going on in DESC. I saw you mentioned Pandoc for converting existing documentation. I’ll take a look at that. Is there a particular editor you prefer for writing reStructuredText from scratch? I’ve looked a little at emacs and vim support for reStructuredText- I try to stay agnostic when it comes to editors 
so I’m willing to give anything a try if it makes writing easier. At the moment, I have access to Linux (SL6), Windows, and an old Mac Mountain Lion laptop - I’m thinking to stick with the Mac for writing doc.
Hi @heather999: to be honest I don’t have a great editor/IDE recommendation for reStructuredText. In a sense that’s a good thing because I think it means you can write reStructuredText easily enough in any editor once you get the hang of it. (My reStructuredText Style Guide page in the Developer Guide attempts to capture the syntax you’ll likely need, but it’s a work in progress.)
My main recommendation is that you work in an environment where you can easily render/preview your work while you write so that you can pick up syntax errors (much as you’d do for LaTeX).
GitHub’s in-browser editing and preview is actually fantastic. See their guide at https://help.github.com/articles/github-flow-in-the-browser/ and an overview blog post at https://github.com/blog/1557-github-flow-in-the-browser. The idea is that you’d edit the rst file in the browser on GitHub and see a GitHub-provided rendering of your text. You save your work by committing to the Git repo.
The one drawback to this approach is that Sphinx supports a broader set of reStructuredText roles and directives (i.e., syntax) that GitHub doesn’t understand. In that case you’ll want to be continuously compiling your Sphinx project locally.
Continuously publishing your documentation to the web is also useful for reducing the friction of documentation writing. Read the Docs is awesome for this. The Developer Guide and DM’s technotes all use Read the Docs, although we’ll be moving to an in-house platform very soon.
I personally use Vim for all of my coding and writing. But this is entirely a personal preference. I like its sense of text motions (I can create an underlined header from a title by typing yypVr=, for instance). I use these plugins specifically to help with writing:
- vim-pencil for dealing with documents that are hard-wrapped (as opposed to letting the editor do the line wrapping).
- Goyo for occasionally building an intensional writing environment.
- Syntastic for linting my reStructuredText (although it does not know about Sphinx’s custom reST syntax)
I also use Vim’s spell checker extensively. And although I don’t do this for reStructuredText yet, you can probably build a useful library of snippets with Ultisnips. My overall Vim setup is at https://github.com/jonathansick/sickvim.
I don’t use Sublime, Emacs or Atom. Perhaps my colleagues can share their tips here. Eventually we can edit this topic into recommendations in DM’s developer guide.
That helps a lot @jsick - I was hesitating to go too far with GitHub’s in-browser editor. And now I feel better about my slight vim over emacs preference I’ll give this a try and see what I encounter as I get more experience. The reStructuredText Style Guide has already been a helpful resource. Ah… I didn’t know about the “LSST The Docs” plan. Thank you for making this all so accessible!