Without a doubt: Robustness! A documentation tool should be able to generate output EVERY TIME. If some files have errors, they should be noted and the rest of the documentation generated. 99% of the files generated is enormously better than 0%. Especially under continuous integration where valid python can break sphinx resulting in NO DOCUMENTATION.
A close second to robustness, is error reporting. If something is wrong with a file, ALWAYS EMIT THE FILENAME! Bonus points for giving a usable hint as to the cause. Extreme kudos for providing a resolution suggestion. Nothing is more aggravating than having to play the which of these 50 files is bombing sphinx this time game! Last today before I get back to playing the which file is bombing sphinx game, is to decouple the documentation tool from the source code's python version. Having to run sphinx (and it's compatible plugins) using python2.7 for python2.7 source target and running running sphinx (and the few compatible plugins) using python3.4 for python3.4 source targets, is for the birds. A documentation tool should be ran using the system python regardless of the version of python the source is targeted at. Yes, this means having to parse the source files instead of using reflection. Good luck and have fun! -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
