From: Guenter M. <mi...@us...> - 2014-05-24 17:14:53
|
On 2014-05-23, Steve Johnson wrote: > (Oops, I didn't reply-all; sorry for the duplicate, David) >> First, please split up the two changes you're proposing. Let's deal >> with your phase 1 & 2 separately. Please start separate threads to >> discuss details. > Can do. I've started experimenting with Sphinx docs on my git fork to > see how feasible it is and will put up a demo soon. I have started a Sphinx-based documentation effort, too. >> VCS/Git: I'm indifferent to a change in VCS. I'd like Docutils to use >> a DVCS, and Git seems to be the leading candidate these days, ... I would welcome a change to git, however I favour to keep the repository on Sourceforge. They support git, so why move elsewhere, require new passwords and setup and getting accustomed to it. I don't like to go to a host just because "everyone ist doing it". Maybe the hurdle for people that thrive there would be lower, but at the cost of current developers and contributors. > I don't have a strong preference in terms of DVCS, but due to its > popularity, I would suggest that GitHub will attract more contributors > to a project without an established large developer community. I don't think that the Docutils core will gain much if it attracts a lot of contributors - the task of keeping the core consistent will become harder. Every patch needs careful consideration and discussion if we want to prevent feature creep and a patchy design. I don't see the set of unhandled patches in the tracker melting by moving to another host. ... >> Doc changes: I'm -1 on switching to using Sphinx for Docutils >> documentation. I'd prefer the Docutils docs and site to be >> pure-Docutils, with no Sphinx extensions. While Sphinx may be the >> single largest user base for Docutils, there are other tools that use >> Docutils without Sphinx. There are some places where Sphinx extensions >> conflict with Docutils syntax, and that would be very confusing for >> non-Sphinx end users. My preference is to use Sphinx for the documentation but keep the sources Docutils-compatible. * "Pure" Docutils is made for single, stand-alone documents. There are several extensions and frameworks using Docutils for the core task to build a site - Sphinx is the most popular and active of them. * Keeping the rst-sources Docutils-compatible will serve twoo needs: a showcase of what is possible with "pure, basic" rst and a reference and example of the "Docutilish" way of doing things. |