From a6b390d996491028b510cc4d61264b637b2a2654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Fri, 6 Oct 2017 01:33:14 +0200 Subject: [PATCH 01/10] Add PHPDoc to developer_docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- Makefile | 12 ++++++++++ composer.json | 6 +++++ developer_manual/index.rst | 1 + generateApiDoc.php | 45 ++++++++++++++++++++++++++++++++++++++ get-server-sources.sh | 13 +++++++++++ 5 files changed, 77 insertions(+) create mode 100644 composer.json create mode 100755 generateApiDoc.php create mode 100755 get-server-sources.sh diff --git a/Makefile b/Makefile index dfb5a864f..ac102c601 100644 --- a/Makefile +++ b/Makefile @@ -38,3 +38,15 @@ user-manual-de-pdf: developer-manual-pdf: cd developer_manual && make latexpdf @echo "Developer manual build finished; PDF is updated" + +api-docs: clean-api-docs + mkdir -p developer_manual/api/ + sh get-server-sources.sh master + composer install + php generateApiDoc.php + +clean: clean-api-docs + rm -r admin_manual/_build developer_manual/_build developer_manual/api user_manual/_build user_manual_de_/_build + +clean-api-docs: + rm -fr developer_manual/api/ diff --git a/composer.json b/composer.json new file mode 100644 index 000000000..b0facd795 --- /dev/null +++ b/composer.json @@ -0,0 +1,6 @@ +{ + "minimum-stability": "dev", + "require": { + "juliushaertl/phpdoc-to-rst": "dev-master" + } +} diff --git a/developer_manual/index.rst b/developer_manual/index.rst index b1f5365d0..bdcfc6a12 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -22,3 +22,4 @@ Table of contents core/index bugtracker/index commun/index + api diff --git a/generateApiDoc.php b/generateApiDoc.php new file mode 100755 index 000000000..956fe40bb --- /dev/null +++ b/generateApiDoc.php @@ -0,0 +1,45 @@ + + * + * @author Julius Härtl + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * + */ + +/* + * This is a short example on how you can generate the API documentation for Nextcloud + */ + +include __DIR__ . '/vendor/autoload.php'; + +use JuliusHaertl\PHPDocToRst\ApiDocBuilder; + +$nextcloudSource = [ + __DIR__ . '/server/lib/public', + __DIR__ . '/server/lib/private', +]; +$destinationDirectory = __DIR__ . '/developer_manual/api'; + +$apiDocBuilder = new ApiDocBuilder($nextcloudSource, $destinationDirectory); +$apiDocBuilder->setVerboseOutput(true); +$apiDocBuilder->setDebugOutput(true); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\InterfaceImplementors::class); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\TocExtension::class); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\PublicOnlyExtension::class); +$apiDocBuilder->build(); + diff --git a/get-server-sources.sh b/get-server-sources.sh new file mode 100755 index 000000000..667c0574a --- /dev/null +++ b/get-server-sources.sh @@ -0,0 +1,13 @@ +#!/bin/bash +# +# Clone Nextcloud server repo into $CWD/server +# if it already exists the latest commits from +# the specified branch will be fetched + +NC_BRANCH="${1:-master}" + +if [ -d server/.git ]; then + cd server && git fetch && git checkout $NC_BRANCH && git reset --hard origin/$NC_BRANCH +else + git clone https://github.com/nextcloud/server server +fi; From 2af85243af0fc37996696a62a27013efd1ad83b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Fri, 13 Oct 2017 00:03:46 +0200 Subject: [PATCH 02/10] PHPDoc: adjust styling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- .../themes/nextcloud_com/static/styles.css | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/_shared_assets/themes/nextcloud_com/static/styles.css b/_shared_assets/themes/nextcloud_com/static/styles.css index 81e9e72d9..fda5e4d50 100644 --- a/_shared_assets/themes/nextcloud_com/static/styles.css +++ b/_shared_assets/themes/nextcloud_com/static/styles.css @@ -1210,3 +1210,101 @@ li > dl > dt { font-weight: 900; } +/* API doc styles */ + +/** Hacky way to display visibility since sphinx-phpdomain currently doesn't seem support them */ + +.public:before { + content: 'public '; +} +.private:before { + content: 'private '; +} +.protected:before { + content: 'protected '; +} +.final dt:before{ + content: 'final '; +} +.abstract dt:before { + content: 'abstract '; +} + +/* Apply rtd default styling to prepended visibility strings */ +.public:before, .private:before { + float: left; +} +.abstract dt:before, +.final dt:before { + padding-right: 10px; +} + +dl.class dt, +dl.interface dt, +dl.trait dt { + font-size: 150%; + margin-bottom: 20px; +} + +.method > dt, +.class > dt, +.interface > dt, +.trait > dt, +.namespace > dt { + padding: 3px; + background-color: #eeeeee; + font-family: Monaco,Menlo,Consolas,"Courier New",monospace; + font-size: 90%; +} +.method:before, +.class:before, +.interface:before, +.trait:before, +.namespace:before { + padding-left: 10px; + padding-top: 1px; + background-color: #eeeeee; + font-family: Monaco,Menlo,Consolas,"Courier New",monospace; + font-size: 90%; + margin-right: 10px; +} +.method > dt code, +.class > dt code, +.interface > dt code, +.trait > dt code, +.namespace > dt code { + background-color: #eeeeee; + font-size: 100%; +} + +/* Hide Fqsn */ +.method .descclassname, +.attr .descclassname { + display: none; +} +.attr .descname:before { + content: '$'; +} + +.method { + margin-bottom: 30px; +} +.method dd { + padding: 10px; +} + +.phpdoctorst th.field-name { + width: 200px; +} + +.phpdoctorst .field-body ul { + padding-left: 0; + list-style-type: none; +} + +.phpdoctorst .line-block { + margin: 0px; +} +.phpdoctorst .line-block .line-block { + margin-left: 15px; +} From 67a61197a0910c1f1fe18fd95dfc7a2dcf4b9d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Tue, 17 Oct 2017 22:58:16 +0200 Subject: [PATCH 03/10] Add python requirements file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- requirements.txt | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..068d52e12 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +sphinx +sphinxcontrib-phpdomain +rst2pdf +pillow From 06086446bfab0dcafff774310df09a8c0cf3a536 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Wed, 18 Oct 2017 14:16:20 +0200 Subject: [PATCH 04/10] Move to build directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- .gitignore | 8 +++- Makefile | 6 +-- .../themes/nextcloud_com/static/styles.css | 42 +------------------ composer.json => build/composer.json | 0 .../generateApiDoc.php | 7 ++-- .../get-server-sources.sh | 0 developer_manual/api.rst | 23 ++++++++++ 7 files changed, 38 insertions(+), 48 deletions(-) rename composer.json => build/composer.json (100%) rename generateApiDoc.php => build/generateApiDoc.php (88%) rename get-server-sources.sh => build/get-server-sources.sh (100%) create mode 100644 developer_manual/api.rst diff --git a/.gitignore b/.gitignore index 18eba7e60..cdc112c31 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,12 @@ # Generated Files */_build/* -conf.pyc +build/vendor/ +build/server/ +build/composer.lock +developer_manual/api/ + +*.pyc # Meta Data .DS_Store @@ -17,3 +22,4 @@ conf.pyc /nbproject/* *.db *.snag + diff --git a/Makefile b/Makefile index ac102c601..3307dcd72 100644 --- a/Makefile +++ b/Makefile @@ -40,10 +40,10 @@ developer-manual-pdf: @echo "Developer manual build finished; PDF is updated" api-docs: clean-api-docs + cd build && sh get-server-sources.sh master mkdir -p developer_manual/api/ - sh get-server-sources.sh master - composer install - php generateApiDoc.php + cd build && composer install && composer update + cd build && php generateApiDoc.php clean: clean-api-docs rm -r admin_manual/_build developer_manual/_build developer_manual/api user_manual/_build user_manual_de_/_build diff --git a/_shared_assets/themes/nextcloud_com/static/styles.css b/_shared_assets/themes/nextcloud_com/static/styles.css index fda5e4d50..65a2dafb6 100644 --- a/_shared_assets/themes/nextcloud_com/static/styles.css +++ b/_shared_assets/themes/nextcloud_com/static/styles.css @@ -1076,7 +1076,8 @@ img.desaturate { h1:hover a.headerlink, h2:hover a.headerlink, h3:hover a.headerlink, -h4:hover a.headerlink { +h4:hover a.headerlink, +.phpdoctorst dt:hover a.headerlink { display: inline; } a.headerlink { @@ -1212,33 +1213,6 @@ li > dl > dt { /* API doc styles */ -/** Hacky way to display visibility since sphinx-phpdomain currently doesn't seem support them */ - -.public:before { - content: 'public '; -} -.private:before { - content: 'private '; -} -.protected:before { - content: 'protected '; -} -.final dt:before{ - content: 'final '; -} -.abstract dt:before { - content: 'abstract '; -} - -/* Apply rtd default styling to prepended visibility strings */ -.public:before, .private:before { - float: left; -} -.abstract dt:before, -.final dt:before { - padding-right: 10px; -} - dl.class dt, dl.interface dt, dl.trait dt { @@ -1256,18 +1230,6 @@ dl.trait dt { font-family: Monaco,Menlo,Consolas,"Courier New",monospace; font-size: 90%; } -.method:before, -.class:before, -.interface:before, -.trait:before, -.namespace:before { - padding-left: 10px; - padding-top: 1px; - background-color: #eeeeee; - font-family: Monaco,Menlo,Consolas,"Courier New",monospace; - font-size: 90%; - margin-right: 10px; -} .method > dt code, .class > dt code, .interface > dt code, diff --git a/composer.json b/build/composer.json similarity index 100% rename from composer.json rename to build/composer.json diff --git a/generateApiDoc.php b/build/generateApiDoc.php similarity index 88% rename from generateApiDoc.php rename to build/generateApiDoc.php index 956fe40bb..199aa30bf 100755 --- a/generateApiDoc.php +++ b/build/generateApiDoc.php @@ -33,13 +33,12 @@ $nextcloudSource = [ __DIR__ . '/server/lib/public', __DIR__ . '/server/lib/private', ]; -$destinationDirectory = __DIR__ . '/developer_manual/api'; +$destinationDirectory = __DIR__ . '/../developer_manual/api'; $apiDocBuilder = new ApiDocBuilder($nextcloudSource, $destinationDirectory); $apiDocBuilder->setVerboseOutput(true); -$apiDocBuilder->setDebugOutput(true); $apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\InterfaceImplementors::class); -$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\TocExtension::class); -$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\PublicOnlyExtension::class); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\NoPrivateExtension::class); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\GithubLocationExtension::class, [__DIR__ . '/server/', 'https://github.com/nextcloud/server']); $apiDocBuilder->build(); diff --git a/get-server-sources.sh b/build/get-server-sources.sh similarity index 100% rename from get-server-sources.sh rename to build/get-server-sources.sh diff --git a/developer_manual/api.rst b/developer_manual/api.rst new file mode 100644 index 000000000..658be997c --- /dev/null +++ b/developer_manual/api.rst @@ -0,0 +1,23 @@ +API Documentation +================= + + +PHP public API +-------------- +.. toctree:: + :maxdepth: 1 + + /OCP namespace + + +PHP class reference +------------------- + +Please note that only APIs in \OCP namespace are considered to be public. The +following documentation is just for reference: + +.. toctree:: + :maxdepth: 1 + + / namespace + /OC namespace From 5f9f229c1c708098e80638105d4cb82cb8af1f3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Wed, 25 Oct 2017 12:30:44 +0200 Subject: [PATCH 05/10] Add api doc to drone --- .drone.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.drone.yml b/.drone.yml index a8dcca2e3..08c22863a 100644 --- a/.drone.yml +++ b/.drone.yml @@ -2,4 +2,5 @@ pipeline: documentation: image: nextcloudci/documentation:documentation-4 commands: + - make api-docs - make all From 99b2b2c091a749a376d7d0cdde0645bad83728bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Wed, 25 Oct 2017 12:31:07 +0200 Subject: [PATCH 06/10] Specify branch for github links in api documentation --- build/generateApiDoc.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build/generateApiDoc.php b/build/generateApiDoc.php index 199aa30bf..7c20a5207 100755 --- a/build/generateApiDoc.php +++ b/build/generateApiDoc.php @@ -39,6 +39,6 @@ $apiDocBuilder = new ApiDocBuilder($nextcloudSource, $destinationDirectory); $apiDocBuilder->setVerboseOutput(true); $apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\InterfaceImplementors::class); $apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\NoPrivateExtension::class); -$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\GithubLocationExtension::class, [__DIR__ . '/server/', 'https://github.com/nextcloud/server']); +$apiDocBuilder->addExtension(\JuliusHaertl\PHPDocToRst\Extension\GithubLocationExtension::class, [__DIR__ . '/server/', 'https://github.com/nextcloud/server', 'master']); $apiDocBuilder->build(); From 558f8e110da3a61600369b665327917c906048c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Wed, 25 Oct 2017 12:31:33 +0200 Subject: [PATCH 07/10] More styling changes for api documentation --- .../themes/nextcloud_com/static/styles.css | 65 +++++++++++++------ 1 file changed, 46 insertions(+), 19 deletions(-) diff --git a/_shared_assets/themes/nextcloud_com/static/styles.css b/_shared_assets/themes/nextcloud_com/static/styles.css index 65a2dafb6..e17ea1200 100644 --- a/_shared_assets/themes/nextcloud_com/static/styles.css +++ b/_shared_assets/themes/nextcloud_com/static/styles.css @@ -1076,8 +1076,7 @@ img.desaturate { h1:hover a.headerlink, h2:hover a.headerlink, h3:hover a.headerlink, -h4:hover a.headerlink, -.phpdoctorst dt:hover a.headerlink { +h4:hover a.headerlink { display: inline; } a.headerlink { @@ -1220,23 +1219,40 @@ dl.trait dt { margin-bottom: 20px; } -.method > dt, -.class > dt, -.interface > dt, -.trait > dt, -.namespace > dt { - padding: 3px; - background-color: #eeeeee; - font-family: Monaco,Menlo,Consolas,"Courier New",monospace; - font-size: 90%; +.phpdoctorst dd .field-list { + margin-top: 20px; + margin-bottom: 40px; + background-color:#f4f4f4; } + .method > dt code, .class > dt code, .interface > dt code, .trait > dt code, .namespace > dt code { - background-color: #eeeeee; font-size: 100%; + color: #333; + background-color: transparent; + font-family: 'Open Sans', Frutiger, Calibri, 'Myriad Pro', Myriad, sans-serif !important; +} + +.method > dt, +.class > dt, +.interface > dt, +.trait > dt, +.namespace > dt { + margin-bottom: 20px; + margin-top: 20px; + font-style: normal !important; + font-size: 120%; +} + +.method > dt em, +.class > dt em, +.interface > dt em, +.trait > dt em, +.namespace > dt em { + font-style: normal !important; } /* Hide Fqsn */ @@ -1248,13 +1264,6 @@ dl.trait dt { content: '$'; } -.method { - margin-bottom: 30px; -} -.method dd { - padding: 10px; -} - .phpdoctorst th.field-name { width: 200px; } @@ -1262,6 +1271,10 @@ dl.trait dt { .phpdoctorst .field-body ul { padding-left: 0; list-style-type: none; + margin: 0; +} +.phpdoctorst .field-body p { + margin: 0; } .phpdoctorst .line-block { @@ -1270,3 +1283,17 @@ dl.trait dt { .phpdoctorst .line-block .line-block { margin-left: 15px; } + +.phpdoctorst .deprecated > dt span, +.phpdoctorst .deprecated > dt code, +.phpdoctorst .deprecated > dt em { + text-decoration: line-through; +} + +.phpdoctorst dt:hover a.headerlink { + display: inline; +} + +.method { + border-bottom: 1px solid #aaa; +} From ad0bd6c8ebe4d59ed8052a1a9a746473ae9fb09a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Wed, 25 Oct 2017 13:28:21 +0200 Subject: [PATCH 08/10] Do not build API reference for pdf documentation --- developer_manual/api.rst | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/developer_manual/api.rst b/developer_manual/api.rst index 658be997c..632f0a0bc 100644 --- a/developer_manual/api.rst +++ b/developer_manual/api.rst @@ -1,23 +1,25 @@ -API Documentation -================= +.. only:: html + + API Documentation + ================= -PHP public API --------------- -.. toctree:: - :maxdepth: 1 + PHP public API + -------------- + .. toctree:: + :maxdepth: 1 - /OCP namespace + /OCP namespace -PHP class reference -------------------- + PHP class reference + ------------------- -Please note that only APIs in \OCP namespace are considered to be public. The -following documentation is just for reference: + Please note that only APIs in \OCP namespace are considered to be public. The + following documentation is just for reference: -.. toctree:: - :maxdepth: 1 + .. toctree:: + :maxdepth: 1 - / namespace - /OC namespace + / namespace + /OC namespace From b20e568aa92d5846c28236a980bcee729b6ba166 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Mon, 4 Dec 2017 23:06:27 +0100 Subject: [PATCH 09/10] Reorder Makefile tasks Signed-off-by: Morris Jobke --- .drone.yml | 1 - Makefile | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.drone.yml b/.drone.yml index 08c22863a..a8dcca2e3 100644 --- a/.drone.yml +++ b/.drone.yml @@ -2,5 +2,4 @@ pipeline: documentation: image: nextcloudci/documentation:documentation-4 commands: - - make api-docs - make all diff --git a/Makefile b/Makefile index 3307dcd72..e63741399 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ user-manual-de-html: cd user_manual_de && make html @echo "User manual de build finished; HTML is updated" -developer-manual-html: +developer-manual-html: api-docs rm -rf developer_manual/_build/html/com cd developer_manual && make html @echo "Developer manual build finished; HTML is updated" @@ -46,7 +46,7 @@ api-docs: clean-api-docs cd build && php generateApiDoc.php clean: clean-api-docs - rm -r admin_manual/_build developer_manual/_build developer_manual/api user_manual/_build user_manual_de_/_build + rm -r admin_manual/_build developer_manual/_build user_manual/_build user_manual_de_/_build clean-api-docs: - rm -fr developer_manual/api/ + rm -r developer_manual/api/ From 2f25f0b507afbd9a81bd85b46ad95b8a9d2b67a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Tue, 5 Dec 2017 08:28:46 +0100 Subject: [PATCH 10/10] Ignore nonexisitng api docs directory when building MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e63741399..f98f77988 100644 --- a/Makefile +++ b/Makefile @@ -49,4 +49,4 @@ clean: clean-api-docs rm -r admin_manual/_build developer_manual/_build user_manual/_build user_manual_de_/_build clean-api-docs: - rm -r developer_manual/api/ + -rm -r developer_manual/api/