I am wondering what the commenting format is in order to have self-documenting code using Sphinx's sphinx-apidoc utility. I am able to get this utility to generate a set of reStructuredText files for each python file, but these files still need to be filled in. I am looking for a way to get this utility, or some other Sphinx utility to generate documentation from the python codes docstrings. I understand this would require becoming familiar with a conventional commenting format, and I am hoping to be pointed to this reference material. Thanks!
Python – using Sphinx’s sphinx-apidoc utility to autogenerate documentation from python code
pythonpython-sphinxsphinx-apidoc
Related Solutions
"Is there a good way to handle this problem?" No. Nothing can be protected against reverse engineering. Even the firmware on DVD machines has been reverse engineered and the AACS Encryption key exposed. And that's in spite of the DMCA making that a criminal offense.
Since no technical method can stop your customers from reading your code, you have to apply ordinary commercial methods.
Licenses. Contracts. Terms and Conditions. This still works even when people can read the code. Note that some of your Python-based components may require that you pay fees before you sell software using those components. Also, some open-source licenses prohibit you from concealing the source or origins of that component.
Offer significant value. If your stuff is so good -- at a price that is hard to refuse -- there's no incentive to waste time and money reverse engineering anything. Reverse engineering is expensive. Make your product slightly less expensive.
Offer upgrades and enhancements that make any reverse engineering a bad idea. When the next release breaks their reverse engineering, there's no point. This can be carried to absurd extremes, but you should offer new features that make the next release more valuable than reverse engineering.
Offer customization at rates so attractive that they'd rather pay you to build and support the enhancements.
Use a license key which expires. This is cruel, and will give you a bad reputation, but it certainly makes your software stop working.
Offer it as a web service. SaaS involves no downloads to customers.
On auto-generating C++ documentation:
After reading up on how to use sphinx at all, you should have a look into breathe:
Breathe provides a bridge between the Sphinx and Doxygen documentation systems.
It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.
So additionally, you'll need to follow Doxygen commenting style and even setup an doxygen project. But I tried that and it works really well after the initial setup took place. Here is an excerpt of our CMakeLists.txt
which might give you an idea on how sphinx and doxygen work together:
macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
add_custom_target(${TARGET_NAME}
COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
WORKING_DIRECTORY docs
DEPENDS doxygen
COMMENT ${COMMENT_STR}
)
endmacro(add_sphinx_target)
add_custom_target(doxygen
COMMAND doxygen docs/doxygen.conf
COMMENT "Build doxygen xml files used by sphinx/breathe."
)
add_sphinx_target(docs-html
html
"Build html documentation"
)
So after initial setup, essentially it boils down to:
- build doxygen documentation with
doxygen path/to/config
cd
into the directory where the sphinx configuration is.- build sphinx documentation with
sphinx-build . path/to/output
On the c++ domain:
Sphinx is a „little bit“ more than a system to auto-generate documentation. I would suggest you have a look at the examples (and consider that the sphinx website itself is written in sphinx reST code). Especially click the Show Source
link on many sphinx-generated pages.
So if you cannot generate documentation automatically for a project, you have to do it yourself. Basically sphinx is a reST to whatever (LaTeX, HTML, …) compiler. So you can write arbitrary text, but the advantage is that it has a lot of commands for documenting source code of different languages. Each language gets its own domain (prefix or namespace) to separate the namespaces of the different languages. So for example I can document a python function using:
.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
Does something nasty with timers in repetition
(source)
I can do the same using the cpp domain:
.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
Describes a method with parameters and types.
(source)
So if you want to document your c++ project without doxygen+breathe but with sphinx, you'll have to write the restructured text files yourself. This also means that you split the documentation from your source code, which can be undesirable.
I hope that clears things up a bit. For further reading I strongly suggest that you have a good read on the sphinx tutorial and documentation until you understood what it actually does.
Best Answer
mzjn, thanks for the comment. your second link provided some good insight on how to format docstrings.
furthermore, i failed to mark the proper sphinx-quickstart prompt answers (as specified in the link, http://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example). particularly, answering yes to:
autodoc: automatically insert docstrings from modules (y/N) [n]:
also, as noted in the link, http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/, and the conf.py comments, i needed to append locations of modules to the system path. i should note that i ran into a problem appending filenames. when i appended paths where modules could be found, everything worked perfectly.