[Maria-developers] Sphinx and other storage engines documentation
Danny, this the log from a short discussion about how to provide the documentation for Sphinx to our users. Can you think of some easy way to automate at least the notification process that the docs changed? <timour> knielsen, shodan IMHO it wuold be best if Sphinx could notify us automatically about changes in the docs, rather than having a possibly outdated documentation, with a link to the up-to-date docs. <timour> If we take this manual approach to copy/paste docs for a dozen storage engines, we will end up in a big mess. <shodan> timour: would http://code.google.com/feeds/p/sphinxsearch/svnchanges/basic do for notifications? <timour> shodan, isn't that a feed with all changes? <shodan> timour: yes, and so doc/ changes are there too <timour> knielsen, perhaps we could pull the docs automatically? <shodan> timour: maybe we could setup a special hook on commits to just doc/ but def not to a specific section <timour> shodan, I think we have to ask our docs guy what is the best way to at least be automatically notified of doc changes (for the same release). <timour> To me there are 2 kinds of doc changes: <timour> - improvements of the docs for the same version of the code, <timour> - changes due to a new release. <timour> The latter will be straightforward, because we will know when we release a new version of Sphinx, but not the former. What do you think about the problem with outdated docs of storage engines? Timour
On Wed, 07 Jul 2010 13:08:46 +0300 Timour Katchaounov <timour@askmonty.org> wrote: Timour> Danny, Timour> Timour> this the log from a short discussion about how to provide the Timour> documentation for Sphinx to our users. Can you think of some Timour> easy way to automate at least the notification process that Timour> the docs changed? Timour> Timour> <timour> knielsen, shodan IMHO it wuold be best if Sphinx could Timour> notify us automatically about changes in the docs, rather than Timour> having a possibly outdated documentation, with a link to the Timour> up-to-date docs. Timour> <timour> If we take this manual approach to Timour> copy/paste docs for a dozen storage engines, we will end up in Timour> a big mess. Timour> <shodan> timour: would Timour> http://code.google.com/feeds/p/sphinxsearch/svnchanges/basic do Timour> for notifications? Timour> <timour> shodan, isn't that a feed with all changes? Timour> <shodan> timour: yes, and so doc/ changes are there too Timour> <timour> knielsen, perhaps we could pull the docs Timour> automatically? Timour> <shodan> timour: maybe we could setup a special hook on commits Timour> to just doc/ but def not to a specific section Timour> <timour> shodan, I think we have to ask our docs guy what is Timour> the best way to at least be automatically notified of doc Timour> changes (for the same release). Timour> <timour> To me there are 2 kinds of doc changes: Timour> <timour> - improvements of the docs for the same version of the Timour> code, Timour> <timour> - changes due to a new release. Timour> <timour> The latter will be straightforward, because we will Timour> know when we release a new version of Sphinx, but not the Timour> former. Timour> Timour> What do you think about the problem with outdated docs of Timour> storage engines? Well, the best way is to get the storage engine developers to update their section of the wiki/knowledgebase whenever it needs updating. I know some devs will be willing do this, but others will not, especially when they have their own documentation procedures in place (like Sphinx does). The next best thing would be to have a notification sent to maria-docs@lists.launchpad.net whenever there are changes to their internal documentation (i.e. the doc/ dir for sphinx), or to the documentation on their site. For Sphinx, Google Code does allow me to have an rss feed that only includes changes to the doc directory: http://code.google.com/feeds/p/sphinxsearch/svnchanges/basic?path=/trunk/doc... Any changes to stuff under /trunk/doc/ will appear in this feed. As an experiment, I imported the feed into feedburner and then used feedburner's "email subscriptions" feature to setup email delivery of new items in the rss feed to the maria-docs@ list. If this works like I think it will this will be a good way to be notified of updates to their docs. What do you think? -- Daniel Bartholomew Monty Program - http://askmonty.org
participants (2)
-
Daniel Bartholomew -
Timour Katchaounov