From abbd2e64c9a6be6e2439ae5e3e771d62fe2e7b85 Mon Sep 17 00:00:00 2001 From: Denis Flaven Date: Mon, 14 Oct 2019 16:43:45 +0200 Subject: [PATCH] Fixed the doc generation and some typos in the README --- .doc/README.md | 18 +++++++++--------- .doc/bin/build-doc-extensions | 5 ++--- .doc/bin/build-doc-object-manipulation | 5 ++--- .doc/composer.json | 6 ++++++ 4 files changed, 19 insertions(+), 15 deletions(-) create mode 100644 .doc/composer.json diff --git a/.doc/README.md b/.doc/README.md index 50a0769df..fb1dd1deb 100644 --- a/.doc/README.md +++ b/.doc/README.md @@ -1,8 +1,8 @@ # Phpdoc dokuwiki template -This directory contains a template rendering iTop phpdoc as wiki pages. +This directory contains a template for rendering iTop phpdoc as dokuwiki pages. -conventional tag that you should use: +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 @@ -14,7 +14,7 @@ conventional tag that you should use: ## Special instructions -some tags where added : +Some iTop specific tags where 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 @@ -39,12 +39,12 @@ examples: #### Do not use inline tags, they do not work properly, example: ``` /** - * This is a texts with ans inline tag {@see [FQSEN] []} it must never be used + * 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 enclose by double quotes + * 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: @@ -82,14 +82,15 @@ Then, **for a method** of an eligible class: ## Installation ``` +cd .doc composer require phpdocumentor/phpdocumentor:~2 --dev ``` ## Generation -`.doc/bin/build-doc-object-manipulation` and `.doc/bin/build-doc-extensions` contains examples of doc. generation, beware: they have to be called from iTop root directory: +`./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 +cd /path/to/itop/.doc +./bin/build-doc-object-manipulation ``` the resulting documentation is written into `data/phpdocumentor/output` @@ -100,4 +101,3 @@ the resulting documentation is written into `data/phpdocumentor/output` * 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 index 77be02873..05480345e 100755 --- a/.doc/bin/build-doc-extensions +++ b/.doc/bin/build-doc-extensions @@ -1,7 +1,6 @@ #!/bin/sh -x -rm -rf /tmp/phpdoc-twig-cache/ && rm -rf data/phpdocumentor/output/extensions/ && rm -rf data/phpdocumentor/temp/extensions/ && vendor/bin/phpdoc -c .doc/phpdoc-extensions.dist.xml -vvv +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 +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 index ca959a26e..2605459ae 100755 --- a/.doc/bin/build-doc-object-manipulation +++ b/.doc/bin/build-doc-object-manipulation @@ -1,8 +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 .doc/phpdoc-objects-manipulation.dist.xml -vvv +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 +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 000000000..2c4a2860f --- /dev/null +++ b/.doc/composer.json @@ -0,0 +1,6 @@ +{ + "require-dev": { + "phpdocumentor/phpdocumentor": "~2", + "jms/serializer": "1.7.*" + } +}