doc:scratchpad:howto

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
doc:scratchpad:howto [2008/12/09 17:53] – reorganized adding new docs, mentioned doc gen, added section for editing old docs, other misc. philipdoc:scratchpad:howto [2014/06/20 12:19] – replaced with a new guide sobak
Line 1: Line 1:
-===== Quick guide for improving the existing PHP documentation ===== +This page has been removed, in favor of [[http://doc.php.net/tutorial/|new guide]]
- +
-=== Getting setup === +
- +
-What you need is: +
-  * Source files of the PHP Manual, which is stored in a CVS module named 'phpdoc' (See: [[http://php.net/anoncvs|anoncvs]]) +
-  <code>$ cvs co phpdoc</code> +
-  * The build system, and it's named [[doc:phd|PhD]] ([[doc:phd:install|See: install guide]]) +
-  <code>$ pear channel-discover doc.php.net +
-$ pear install doc.php.net/phd-beta</code> +
-  * A text editor (any will do) +
-  * Knowledge of the [[http://doc.php.net/php/dochowto/chapter-conventions.php|coding standards]]:  +
- +
-Before you get started documenting you should make sure the tool chain and your checkout is okay. To do so, consider the following scenario: +
-<code> +
-  $ phd -V (check to see if phd is installed, and in the path) +
-  $ cd phpdoc (make the manual sources your current directory) +
-  $ php configure.php -V (check to see if this works) +
-  $ php configure.php (This will create a huge .manual.xml file which PhD uses to render the docs) +
-  $ phd -d .manual.xml -f xhtml -t chunkedhtml (Creates an html/ folder few thousand files) +
-</code> +
- +
-Poke around the **html/** directory and open up some of the files in you favorite browser to see if everything is fine. +
- +
-=== Knowing the structure === +
- +
-The documentation for extensions is located in: +
- +
-  /phpdoc/en/reference/extension_name/ +
- +
-For example, the SVN extension documentation exists in: +
-  +
-  /phpdoc/en/reference/svn/ +
- +
-There you'll find several files: +
- +
-  * //book.xml// (Acts as the container for the extension and contains the preface) +
-  * //setup.xml// (Includes setup, install and configuration documentaiton) +
-  * //constants.xml// (Lists all constants the extension declares, if any) +
-  * //configure.xml// (Usually this information is in setup.xml, but if the file exists it is magically included into setup.xml) +
- +
-For procedural extension (like SVN) you also have: +
- +
-  * //reference.xml// (container for the functions, rarely contains any info) +
-  * //functions///    (folder with one XML file per function that the extension declares) +
- +
-For OO extensions (such as imagick) you have: +
- +
-  * //classname//.xml (container for the methods defined by the class, contains also basic info about it) +
-  * //classname///    (folder with one XML per method that the class declares) +
- +
-  * Note: "//classname//" is the lowercased name of the class, not a literal file or directory name. +
- +
-=== Editing existing documentation === +
-Simply open the files and edit them. Remember to follow the "coding standard" described in the documentation howto. And after it validates, commit. +
-<code> +
-$ vim phpdoc/en/reference/strings/strlen.xml +
-$ php configure.php +
-$ cvs commit phpdoc/en/reference/strings/strlen.xml -m "Added SeeAlso strpos()" +
-</code> +
- +
-=== Adding new documentation === +
- +
-When adding new functions or methods, there are a couple of options. Either way, the generated (or copied) files will need to be filled out. +
- +
-== Option A: Copy skeleton files == +
-This involves copying the skeleton files into the correct location: +
- +
-<code> +
-  cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml   (for new methods) +
-  cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions) +
-</code> +
- +
-  * Note: "classname" is the lowercased name of the class, not a literal file name. +
-  * Note: "methodname" is the lowercased name of the method name, not a literal file name. +
-  * Note: "functionname" is the lowercased name of the function name, not a literal file name. +
- +
-== Option B: Generating files using docgen == +
-The docgen script is found within the php documentation (phpdoc/scripts/docgen/) and uses Reflection to generate documentation (DocBook) files. See the [[doc:scratchpad:pecldocs|PECL Docs]] section for details. +
- +
-=== Testing the changes === +
- +
-Methods and functions are automagically included into the hierarchy so you don't have to "configure" anything, just run "//php configure.php//" to build the .manual.xml and validate the changes. If no error occur it means you changes validated. +
- +
-Now its time to check the rendering: +
- +
-<code> +
-  $ phd -d .manual.xml -f xhtml -t chunkedhtml +
-</code> +
- +
-This will create a "**html/**" directory in your current working directory. Open up the files you just added in your browser and make sure everything is fine (the filenames are taken from the "xml:id" attribute on the root element of the XML file). +
- +
-If everything is looking good, its time to post the changes. +
- +
-=== Committing the changes === +
- +
-== Creating patches == +
- +
-If you edited existing documentation you will have to create a patch. The following will iterate recursively over the directory and push all changes into the changes.patch file: +
- +
-<code> +
-  $ cvs diff -u > changes.patch +
-</code> +
- +
-If you added new files you will have to create an archive of the new files you added (tar -cf changes.tar file1.xml file2.xml file3.xml). +
- +
-Then upload the archive (or patch file) to http somewhere and post the link to phpdoc@lists.php.net including a short summary of what you did. +
- +
-And later committing them yourself +
- +
-== Committing patches == +
- +
-If you have CVS karma then there is no need to create patches... just commit!  +
- +
doc/scratchpad/howto.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools