Code documentation tool in need
As a student who writes code very often, I want a perfect tool to make my code well documented. By the word documentation, I mean, not only the comment lines in the source code, but also something like the introduction of the code/program, user manual, tutorial, getting started page, etc..
By now, I have tried MS word, LaTeX, Mardown, Github page and even the text file to write documentations for my own code. And also used a Shpinx for an open source program (pyne) I am working on.
Technologies are continually being developed, there are several good tools to make code documentation. It’s time to choose one that meets all my requirements:
- System independent. This tool should be available for all operating systems, include Windows, Linux and Mac.
- Open source. Open source means I can access to it without any restriction, and I may also make changes to the source code.
- Multiple programming language support. I am now using python, C++ and fortran. The ideal tool should support all these languages. The more, the better.
- Multiple language support. As a native Chinese speaker, there will be as much communications in Chinese as in English.
- Git/Github compatibility. The documentation itself should also be recorded and managed on github.
- Multiple output format support. For the documentation, I want at least a local version in text file (such as README.md), a PDF version (should support LaTeX format support), a online HTML version.
- Convenient cross reference. Documentations contain contents highly related to each other, cross reference support enables user to jump to related content at a click.
Available choices
I have listed the features I want. Now, let’s look at the available tools for code documentation. There are two popular documentation tools: Doxygen and Sphinx.
Doxygen
Doxygen is a great tool for generating documentation from source code. The tool is aimed at C++, but it can also be used with PHP, Java, Python, etc. With the help of Doxygen, you can create online HTML documentation. It can also be used to generate output in multiple formats, including Unix man pages, PostScript, etc.
The biggest advantage of using Doxygen is that you will have consistency throughout your source code documentation. It can also help you to generate code structure using the undocumented source files. All you need to do is configure it accordingly.
Detail features of Doxygen could be found here.
Sphinx
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.
Sphinx has the following features:
- Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
- Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
- Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
- Automatic indices: general index as well as a language-specific module indices
- Code handling: automatic highlighting using the Pygments highlighter
- Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
- Contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI
Compare
According to my requirement, how do these two documentation tools behave? See the table below:
| Tool | Doxygen | Sphinx |
|---|---|---|
| System independent | Unix, Windows | Linux, Windows, Mac |
| Open source | Yes. Writen in C++ | Yes. Written in python |
| Programming language support | C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D | Python, Javascript, PHP, Java, Go, Erlang, R, .Net |
| Language support | en, zh_CN, etc. | en, zh_CN, etc. |
| Git/Github compatibility | Yes | Yes |
| Output format | HTML, LaTeX, RTF, XML, Man page, DocBook | HTML, epub, LaTeX, text, manual page, Texinfo |
| Corss reference | Yes | Yes |
Now we found that both Doxygen and Sphinx meet my need. However, during the research process, I find that I prefer Sphinx for two reasons:
- Sphinx is written in python.
- Documentation is independent of the source code