Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Is there a tool like AsciiDoc or reStructuredText that is simple enough, like a standalone Python file, to be embedded in the repository of the associated project I'm writing documentation for? Assume that I want to add exemples of code and images in such documentation. Obviously it have to be cross-platform so I'm thinking about Python script as it's available almost anywhere.

Clarification : I'm looking for 1 stand-alone python script (that generates the doc from other sources) that I can put in my project's repository to allow the repository users to easily re-generate the documentation with only one requirement : to have python installed - and only python alone.

Clarification 2 : I do not need documentation generated from code, I need a tool/script to write documentation that can be embedded in the repository of the project, with minimum overhead (like file numbers and size).

share|improve this question

closed as off-topic by gnat, Dan Pichelman, MichaelT, GlenH7, mattnz Sep 19 '13 at 2:52

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – gnat, Dan Pichelman, MichaelT, GlenH7, mattnz
If this question can be reworded to fit the rules in the help center, please edit the question.

What's wrong with RST-based documentation? It's simple enough and is stand-alone source, and contains code samples with markup. What's wrong with RST? –  S.Lott Jul 18 '11 at 14:19
Maybe I'm wrong but the documentation tells to install some python application. I didn't check if it was 1 python file, thought it was like asciidoc... will check. –  Klaim Jul 18 '11 at 15:03
"the documentation tells to install some python application"? What problem are you having? What do you want to do that you can't do? It's not clear from the question and comments what problem you actually have. –  S.Lott Jul 18 '11 at 15:06
1 python script that I can put in my project's repository to allow the repository users to easily re-generate the documentation with only one requirement : to have python installed - and only python alone. –  Klaim Jul 18 '11 at 15:13
That's a weird requirement ("python installed - and only python alone"). But it's important, so please update the question to specifically say that. The question is not clear. –  S.Lott Jul 18 '11 at 15:47
show 1 more comment

4 Answers

Try markdown which is a single perl script implementation.

It has a syntax very similar to asciidoc and can be feed to a number of more advanced tools as well, e.g. pandoc.

I believe stackexchange uses a flavor of markdown for it's post markup.

share|improve this answer
@downvoter: Please comment so I can improve my answer. –  Benjamin Bannier Jul 18 '11 at 16:48
I didn't downvote, but I don't think this really answers the OP's question. The OP is asking for software to automatically generate documentation. –  Robert Harvey Jul 18 '11 at 17:29
@Robert I read him asking about tools to generate documentation in general, not from source (like e.g. doxygen or sphinx do). –  Benjamin Bannier Jul 18 '11 at 18:21
That's right, general doc, not from source. –  Klaim Dec 2 '11 at 11:12
add comment

You can use DocBook XML. Quite rich interface, and a lot of possible output formats depending on your target device.


share|improve this answer
I'm abandoning DocBook in my project — it's very verbose to the point I'm reluctant to update the documentation and it's very detailed semantics are not needed when converting to HTML. The processor I used — xmlto — looks like half-dead project and isn't easy to install (e.g. I can't send the manual to translators and expect them to see results on Windows machines). –  porneL Aug 23 '11 at 20:35
add comment

Perhaps Doxygen will do what you need. It is not a python script, but it will create documentation from python code. Usually it is installed separately as tool.

share|improve this answer
add comment

AsciiDoc and reST are just plain text, you can edit with any editor or coding IDE, optional helper tools available for many platforms.

The toolchain you use to "generate the docs" depends on what your target output is. AsciiDoc offers a lot more target paths and is more oriented toward longer, structured texts, including full books. reST itself is really more just the syntax for structuring your inline text, whether in standalone text files or embedded in code - it is used by the Python developers for documenting their codebase. You might want to look at Sphinx, which extends reST to be more structural if you want the larger featureset of AsciiDoc.

In either case anyone wanting to generate "the docs" will need the appropriate tools to do so, and when you say "only have Python installed" that implies to me that you're looking for toolchains based on scripts written only in Python - you don't even want e.g. bash shell scripts? If that's the case I think the answer is "no".

Usually the person or team that writes and maintains the docs generates the target output(s) into format(s) that can be read easily with tools they already have - PDF, straight HTML or compiled HTML_help, these days maybe EPUB/mobi ebooks.

If your goal is for everyone touching the source to be able to contribute to the code, having a lightweight markup like these two will allow for that, as the source files are diff'd via your VCS just like the code. But generating the output formats will require the appropriate toolchain to be set up. IMO this isn't an issue, since the person/team responsible for docs quality and accuracy should be verifying the changes before "publishing" the next version of the finished output formats.

But the source files will remain "living" docs, open to all.

Hope this helps clarify your thinking.

share|improve this answer
Sorry but you're assuming too much about what I need. First there is no big team, just me, there is no people specifically responsible for generating the doc; second it's for short projects that can be developped on different contexts that have only one common programming tool that is python; third I cannot change those contexts, and they can be on different OSes. Your answer don't help a lot, as you're assuming that I don't need what I'm asking for, that is obvioulsy wrong for someone in my specific context. Now, you're saying that "no" it don't exists, I'll assume that's youre real answer. –  Klaim Dec 2 '11 at 11:11
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.