Having worked with ReST a lot before, I'm +1 on this. It's fairly elegant once you get past some of the quirks.
As I'm finding in other environments, writing documentation usually comes down to cultural barriers rather than technological ones. People will adapt to the tool; it's getting them to write docs in the *first* place that's usually the problem (that point being only tangentially related to this discussion). On Fri, Mar 1, 2013 at 2:40 PM, Tomaz Muraus <[email protected]> wrote: > I would love to hear other people take on this. > > I think it's a step in the right direction and we should do it (reasons are > already listed in the ticket description). It also aligns up with a site > re-design / revamp which should be coming up in te near future. > > ---------- Forwarded message ---------- > From: Tomaz Muraus (JIRA) <[email protected]> > Date: Fri, Mar 1, 2013 at 2:29 PM > Subject: [dev] [jira] [Created] (LIBCLOUD-301) Consider switching > documentation from custom Markdown to Sphinx + ReST > To: [email protected] > > > Tomaz Muraus created LIBCLOUD-301: > ------------------------------------- > > Summary: Consider switching documentation from custom Markdown > to Sphinx + ReST > Key: LIBCLOUD-301 > URL: https://issues.apache.org/jira/browse/LIBCLOUD-301 > Project: Libcloud > Issue Type: Task > Components: Documentation, Website > Reporter: Tomaz Muraus > > > Consider moving documentation (http://libcloud.apache.org/docs/) to Sphinx. > > Reasons: > > - It's more idomatic / in Python world Sphinx is the standard > - We can also host it on readthedocs which is turning out to become a > defacto standard for hosting docs for Python libraries > > Downsides: > > - Currently docs are constitent with other website content and use > Markdown. For Sphinx we would need to use ReST. > > -- > This message is automatically generated by JIRA. > If you think it was sent incorrectly, please contact your JIRA > administrators > For more information on JIRA, see: http://www.atlassian.com/software/jira -- Jed Smith +1 (609) 742-4715 [email protected]
