[Phpmyadmin-devel] Documentation
Hi for quite some time I was thinking about way we provide documentation and I think there is lot of place for improvements. As my current favorite tool to build documentation is Sphinx <http://sphinx.pocoo.org/>, I gave it a try. To name some of the benefits let me quote from their home page: * Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text * Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information * Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children * Automatic indices: general index as well as a module index * Built-in fulltext search I've done quick and dirty [*] conversion of FAQ and few introductory sections, you can find source here: https://github.com/nijel/phpmyadmin-doc And the generated documentation in HTML and PDF here: http://tmp.cihar.com/pmadoc/index.html http://tmp.cihar.com/phpMyAdmin.pdf What do you think about changing our documentation from HTML to something else (be it Sphinx, Docbook or something completely else)? [*] I've lost all text formatting and links in text, but that should not be hard to convert properly, I just did not want to spend much time on prototype. -- Michal Čihař | http://cihar.com | http://phpmyadmin.cz
Michal Čihař a écrit :
Hi
for quite some time I was thinking about way we provide documentation and I think there is lot of place for improvements.
As my current favorite tool to build documentation is Sphinx <http://sphinx.pocoo.org/>, I gave it a try. To name some of the benefits let me quote from their home page:
* Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text * Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information * Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children * Automatic indices: general index as well as a module index * Built-in fulltext search
I've done quick and dirty [*] conversion of FAQ and few introductory sections, you can find source here:
https://github.com/nijel/phpmyadmin-doc
And the generated documentation in HTML and PDF here:
http://tmp.cihar.com/pmadoc/index.html
http://tmp.cihar.com/phpMyAdmin.pdf
What do you think about changing our documentation from HTML to something else (be it Sphinx, Docbook or something completely else)?
[*] I've lost all text formatting and links in text, but that should not be hard to convert properly, I just did not want to spend much time on prototype.
Hi Michal, this Sphinx format seems easy to work with; it would be a good improvement. -- Marc Delisle http://infomarc.info
Hi all I've spent some more time to convert basically all our docs into Sphinx <http://sphinx.pocoo.org/> format. I know the conversion right now has messed up some parts, but that's quite easy to fix in future in case we decide to use it (I think that broken bits are easier to fix manually than torturing more the conversion script). What I would like to hear from you is if we should go this way or not. Previously only Marc told he likes this but no other reaction. Now I'd like to hear from more people :-). If there won't be objections, I'd really like to get rid of HTML documentation ASAP. The docs sources and migration code lives on github: https://github.com/nijel/phpmyadmin-doc The generated documentation is on readthedocs: https://phpmyadmin.readthedocs.org You can also download there other formats like PDF or Epub: https://readthedocs.org/projects/phpmyadmin/downloads/ -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Quoting Michal ?iha? <michal@cihar.com>:
Hi all
I've spent some more time to convert basically all our docs into Sphinx <http://sphinx.pocoo.org/> format. I know the conversion right now has messed up some parts, but that's quite easy to fix in future in case we decide to use it (I think that broken bits are easier to fix manually than torturing more the conversion script).
What I would like to hear from you is if we should go this way or not. Previously only Marc told he likes this but no other reaction. Now I'd like to hear from more people :-).
If there won't be objections, I'd really like to get rid of HTML documentation ASAP.
The docs sources and migration code lives on github:
https://github.com/nijel/phpmyadmin-doc
The generated documentation is on readthedocs:
https://phpmyadmin.readthedocs.org
You can also download there other formats like PDF or Epub:
https://readthedocs.org/projects/phpmyadmin/downloads/
-- Michal ?iha? | http://cihar.com | http://blog.cihar.com
I like it, so I'm in favor of this. Bye, Rouslan
Hi Dne Thu, 8 Nov 2012 17:32:41 +0100 Michal Čihař <michal@cihar.com> napsal(a):
I've spent some more time to convert basically all our docs into Sphinx <http://sphinx.pocoo.org/> format. I know the conversion right now has messed up some parts, but that's quite easy to fix in future in case we decide to use it (I think that broken bits are easier to fix manually than torturing more the conversion script).
Most of the issues should be now fixed, I believe the new docs is ready to be used. Please check https://phpmyadmin.readthedocs.org [*] if you don't see any major problems. The question is whether we want to keep documentation in same repository as code or keep it separately. The same question applies for translations of documentation. [*]: Or sources at https://github.com/nijel/phpmyadmin-doc -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Michal Čihař a écrit :
Hi
Dne Thu, 8 Nov 2012 17:32:41 +0100 Michal Čihař <michal@cihar.com> napsal(a):
I've spent some more time to convert basically all our docs into Sphinx <http://sphinx.pocoo.org/> format. I know the conversion right now has messed up some parts, but that's quite easy to fix in future in case we decide to use it (I think that broken bits are easier to fix manually than torturing more the conversion script).
Most of the issues should be now fixed, I believe the new docs is ready to be used.
Please check https://phpmyadmin.readthedocs.org [*] if you don't see any major problems.
The question is whether we want to keep documentation in same repository as code or keep it separately. The same question applies for translations of documentation.
I see a reason to keep doc and translations in the same repository as the code: when you want to "git grep" for a configuration directive or for a specific message.
[*]: Or sources at https://github.com/nijel/phpmyadmin-doc
-- Marc Delisle http://infomarc.info
Dne Fri, 09 Nov 2012 12:16:08 -0500 Marc Delisle <marc@infomarc.info> napsal(a):
Michal Čihař a écrit :
Hi
Dne Thu, 8 Nov 2012 17:32:41 +0100 Michal Čihař <michal@cihar.com> napsal(a):
I've spent some more time to convert basically all our docs into Sphinx <http://sphinx.pocoo.org/> format. I know the conversion right now has messed up some parts, but that's quite easy to fix in future in case we decide to use it (I think that broken bits are easier to fix manually than torturing more the conversion script).
Most of the issues should be now fixed, I believe the new docs is ready to be used.
Please check https://phpmyadmin.readthedocs.org [*] if you don't see any major problems.
The question is whether we want to keep documentation in same repository as code or keep it separately. The same question applies for translations of documentation.
I see a reason to keep doc and translations in the same repository as the code: when you want to "git grep" for a configuration directive or for a specific message.
Indeed I see this as an advantage as well. -- Michal Čihař | http://cihar.com | http://phpmyadmin.net
Hi As I did not see any objections, here is pull request with new documentation: https://github.com/phpmyadmin/phpmyadmin/pull/108 -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Michal Čihař a écrit :
Hi
As I did not see any objections, here is pull request with new documentation:
Merged, thanks. A few questions: 1. Is https://phpmyadmin.readthedocs.org generated from the phpmyadmin repo or yours? 2. Are you keeping control of https://readthedocs.org/projects/phpmyadmin/ for yourself? 3. Should http://www.phpmyadmin.net/documentation/ point to https://readthedocs.org/projects/phpmyadmin/downloads/ ? -- Marc Delisle http://infomarc.info
Dne Mon, 12 Nov 2012 07:44:46 -0500 Marc Delisle <marc@infomarc.info> napsal(a):
Michal Čihař a écrit :
Hi
As I did not see any objections, here is pull request with new documentation:
Merged, thanks. A few questions:
1. Is https://phpmyadmin.readthedocs.org generated from the phpmyadmin repo or yours?
Now switched to phpMyAdmin repo.
2. Are you keeping control of https://readthedocs.org/projects/phpmyadmin/ for yourself?
Yes, unfortunately I don't see way to make it group owned.
3. Should http://www.phpmyadmin.net/documentation/ point to https://readthedocs.org/projects/phpmyadmin/downloads/ ?
I'd rather say to phpmyadmin.readthedocs.org, working on this. -- Michal Čihař | http://cihar.com | http://blog.cihar.com
Hi I've started a wiki page describing some of the documentation: http://wiki.phpmyadmin.net/pma/Documentation -- Michal Čihař | http://cihar.com | http://blog.cihar.com
2012/11/12 Michal Čihař <michal@cihar.com>:
Hi
I've started a wiki page describing some of the documentation:
Hi, I was wondering if the documentation is generated from the *.rst files in the /doc folder. In other words, should we update the .rst files and then generate the docs, or are the .rst files generated from some other files? -- Kind regards, Dieter Adriaenssens
Hi Dne Thu, 29 Nov 2012 16:23:48 +0100 Dieter Adriaenssens <dieter.adriaenssens@gmail.com> napsal(a):
I was wondering if the documentation is generated from the *.rst files in the /doc folder. In other words, should we update the .rst files and then generate the docs, or are the .rst files generated from some other files?
Yes, the documentation is generated from *.rst files in doc folder. -- Michal Čihař | http://cihar.com | http://blog.cihar.com
2012/11/29 Michal Čihař <michal@cihar.com>:
Hi
Dne Thu, 29 Nov 2012 16:23:48 +0100 Dieter Adriaenssens <dieter.adriaenssens@gmail.com> napsal(a):
I was wondering if the documentation is generated from the *.rst files in the /doc folder. In other words, should we update the .rst files and then generate the docs, or are the .rst files generated from some other files?
Yes, the documentation is generated from *.rst files in doc folder.
FYI : I added a small section on the wiki about updating the *.rst files to change the documenation. -- Kind regards, Dieter Adriaenssens
participants (4)
-
Dieter Adriaenssens -
Marc Delisle -
Michal Čihař -
rouslan＠placella.com