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ř 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.
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/
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-docThe generated documentation is on readthedocs:
https://phpmyadmin.readthedocs.orgYou 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ř 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
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.
Hi
As I did not see any objections, here is pull request with new documentation:
https://github.com/phpmyadmin/phpmyadmin/pull/108
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/ ?
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:
- Is https://phpmyadmin.readthedocs.org generated from the phpmyadmin
repo or yours?
Now switched to phpMyAdmin repo.
- Are you keeping control of
https://readthedocs.org/projects/phpmyadmin/ for yourself?
Yes, unfortunately I don't see way to make it group owned.
- Should http://www.phpmyadmin.net/documentation/ point to
I'd rather say to phpmyadmin.readthedocs.org, working on this.
Hi
I've started a wiki page describing some of the documentation:
http://wiki.phpmyadmin.net/pma/Documentation
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?
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.
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.
-
Dieter Adriaenssens -
Marc Delisle -
Michal Čihař -
rouslan＠placella.com