Hi Devs, I noticed the work going on in branch "flume-1262", which appears to involve porting the existing RST docs to xdoc. I guess this is in response to a couple of concerns some people have raised: (1) Maven 2 isn't compatible with the way Sphinx is integrated with the build currently <https://issues.apache.org/jira/browse/FLUME-1282>, and (2) it appears that invoking Jython to run Sphinx takes more than the default amount of memory allocated to Maven (requires setting MAVEN_OPTS to increase the memory for the build) <https://issues.apache.org/jira/browse/FLUME-1256>.
Since these issues have clear workarounds, I haven't set aside the time to try to fix them myself. However, I thought it might be a good idea to discuss openly on the dev list whether switching to another format makes sense (and if so, which one). It seems that xdoc was mostly replaced by APT (almost plain text) in Maven 2 (according to https://maven.apache.org/doxia/references/xdoc-format.html ). I wonder if there is a reason why Maven rewrote all their documentation in APT. While I'm sure RST and Jythonized Sphinx have some drawbacks, they also have the following benefits: - RST is meant to be very readable in source form - Even tables are readable in source form and are easy to maintain - Sphinx is skinnable / themeable and widely used in Python land - Can output to HTML and PDF I'm certainly not against moving to something else, but it might be a good idea to get consensus on a direction before going and independently reformatting all the documentation. Since the existing docs are already editable by the community, and people have been submitting patches to them (while the previous HTML was totally unmaintainable), let's make sure we end up with something better if we decide to replace it. Regards, Mike
