Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I really like ReadTheDocs and I like this encouragement to write documentation but I think it'd be good to add more information that isn't specific to use RST and Sphinx for non-Python developers. I personally really like RST and Sphinx but it'd be a good way to make this a common resource.


I think being opinionated about which tools to use is fine, as long as it's clear that it's an opinion. I'd add my praise to what other's have said.

One thing that strikes me is that installing python might be difficult for windows users, especially if their PC is locked down (I have added a pull request (edit: merged) with a link to Sphinx's instructions for windows, though that doesn't help people with locked down PCs). It may be worth linking to http://rst.ninjs.org/ which is an online reStructed Text Editor with live preview. It is perhaps lamentable that Windows is still a dominant desktop OS.


Markdown and RST have a common subset, and all examples given are only making use of that common subset, as I understand it.


The beginners guide is explicitly using general markup, instead of Sphinx specifically. Almost none of the content on the site is actually Sphinx-specific..




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: