diff --git a/.doc/README.md b/.doc/README.md new file mode 100644 index 0000000000..6221bf2c16 --- /dev/null +++ b/.doc/README.md @@ -0,0 +1,103 @@ +# Phpdoc dokuwiki template +This directory contains a template for rendering iTop phpdoc as dokuwiki pages. + + +Conventional tags that you should use: + * `@internal` : exclude from the documentation. + * `@api` : it means that a method is an api, thus it may be interacted with. + * `@see` : it points to another documented method + * `@link` : external url + * if you point to another page of the wiki, please use relative links. + * `@example` : let you provide example of code + * `@param`, `@return`, `@throws`, ... + + +## Special instructions + +Some iTop specific tags were added : + * `@api-advanced`: it means that a method is an `@api` but mark it also as "complex" to use + * `@overwritable-hook`: used to mark a method as "designed to be extended" + * `@extension-hook`: not used for now + * `@phpdoc-tuning-exclude-inherited`: once this tag is present on a class, it's inherited methods won't be showed. + + +### known limitations: +#### `@see` tags must be very specific: + * always prefix class members with `ClassName::` + * for methods always suffix them with `()`, + * do not reference variables since they are not documented. If you have to, always prefix them with `$` + +examples: +``` +/** + * @see DBObject + * @see DBObject::Get() + * @see DBObject::$foo + */ +``` + +#### Do not use inline tags, they do not work properly, example: +``` +/** + * This is a texts with an inline tag {@see [FQSEN] []} it must never be used + */ +``` + +#### The `@example` tag must respect this very precise syntax + * the sentence in the first line (next to the tag) is the title, it must be enclosed by double quotes + * the following lines are the sample code. + * 💔 since we simply hack the official tag, this syntax must be respected carefully 💔 +example: +``` +/** +* @example "This is the title of the multiline example" +* $foo = DBObject::Get('foo'); +* DBObject::Set('foo', ++$foo); +*/ +``` + +## How content is included into the documentation + +**For a class** those requirements have to be respected: + - the file containing the class must be listed in `/phpdoc/files/file[]` of `.doc/phpdoc-objects-manipulation.dist.xml` + - the class **must not** have the tag `@internal` + - the class **must** have at least one of: `@api`, `@api-advanced`, `@overwritable-hook`, `@extension-hook` + +Then, **for a method** of an eligible class: + - **public** methods **must** have at least one of: `@api`, `@api-advanced`, `@overwritable-hook`, `@extension-hook` + - **protected** methods **must** have at least one of: `@overwritable-hook`, `@extension-hook` + - **private** methods are **always excluded** + +**Class properties** and **constants** are never documented (this is subject to change). + + + + +## A note about the rendering engine + +:notebook: as spaces are used to mark code, the templates (`.doc/phpdoc-templates/combodo-wiki/*`) have very few indentation, thus they are awful to read (sorry). + + + + +## Installation +``` +cd .doc +composer require phpdocumentor/phpdocumentor:~2 --dev +``` + +## Generation +`./bin/build-doc-object-manipulation` and `./bin/build-doc-extensions` contains examples of doc. generation, beware: they have to be called from the .doc directory: +```shell +cd /path/to/itop/.doc +./bin/build-doc-object-manipulation +``` + +the resulting documentation is written into `data/phpdocumentor/output` + + +## Dokuwiki requirements + * the template uses the [wrap plugin](https://www.dokuwiki.org/plugin:wrap). + * the generated files have to be placed under an arbitrary directory of `[/path/to/dokuwiki]/data/pages`. + * the html has to be activated [config:htmlok](https://www.dokuwiki.org/config:htmlok) + * the generated files have to be in lowercase diff --git a/.doc/bin/build-doc-extensions b/.doc/bin/build-doc-extensions new file mode 100755 index 0000000000..05480345e5 --- /dev/null +++ b/.doc/bin/build-doc-extensions @@ -0,0 +1,6 @@ +#!/bin/sh -x + +rm -rf /tmp/phpdoc-twig-cache/ && rm -rf data/phpdocumentor/output/extensions/ && rm -rf data/phpdocumentor/temp/extensions/ && .doc/vendor/bin/phpdoc -c .doc/phpdoc-extensions.dist.xml -vvv + +# now wee need to lowercase every generated file because dokuwiki can't handle uppercase +cd data/phpdocumentor/output/extensions/ && for i in $( ls | grep [A-Z] ); do mv -i $i `echo $i | tr 'A-Z' 'a-z'`; done \ No newline at end of file diff --git a/.doc/bin/build-doc-object-manipulation b/.doc/bin/build-doc-object-manipulation new file mode 100755 index 0000000000..2605459ae2 --- /dev/null +++ b/.doc/bin/build-doc-object-manipulation @@ -0,0 +1,7 @@ +#!/bin/sh -x + +rm -rf /tmp/phpdoc-twig-cache/ && rm -rf ../data/phpdocumentor/output/objects-manipulation/ && rm -rf ../data/phpdocumentor/temp/objects-manipulation/ && ./vendor/bin/phpdoc -c ./phpdoc-objects-manipulation.dist.xml -vvv + + +# now wee need to lowercase every generated file because dokuwiki can't handle uppercase +cd ../data/phpdocumentor/output/objects-manipulation/ && for i in $( ls | grep [A-Z] ); do mv -i $i `echo $i | tr 'A-Z' 'a-z'`; done \ No newline at end of file diff --git a/.doc/composer.json b/.doc/composer.json new file mode 100644 index 0000000000..2c4a2860f0 --- /dev/null +++ b/.doc/composer.json @@ -0,0 +1,6 @@ +{ + "require-dev": { + "phpdocumentor/phpdocumentor": "~2", + "jms/serializer": "1.7.*" + } +} diff --git a/.doc/phpdoc-extensions.dist.xml b/.doc/phpdoc-extensions.dist.xml new file mode 100755 index 0000000000..826cd61f24 --- /dev/null +++ b/.doc/phpdoc-extensions.dist.xml @@ -0,0 +1,20 @@ + + + <![CDATA[iTop extensions]]> + + + ../data/phpdocumentor/temp/extensions + + + + ../data/phpdocumentor/output/extensions + + + +