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 dfb5a864f..f98f77988 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" @@ -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 + cd build && sh get-server-sources.sh master + mkdir -p developer_manual/api/ + cd build && composer install && composer update + cd build && php generateApiDoc.php + +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/ diff --git a/_shared_assets/themes/nextcloud_com/static/styles.css b/_shared_assets/themes/nextcloud_com/static/styles.css index 81e9e72d9..e17ea1200 100644 --- a/_shared_assets/themes/nextcloud_com/static/styles.css +++ b/_shared_assets/themes/nextcloud_com/static/styles.css @@ -1210,3 +1210,90 @@ li > dl > dt { font-weight: 900; } +/* API doc styles */ + +dl.class dt, +dl.interface dt, +dl.trait dt { + font-size: 150%; + margin-bottom: 20px; +} + +.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 { + 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 */ +.method .descclassname, +.attr .descclassname { + display: none; +} +.attr .descname:before { + content: '$'; +} + +.phpdoctorst th.field-name { + width: 200px; +} + +.phpdoctorst .field-body ul { + padding-left: 0; + list-style-type: none; + margin: 0; +} +.phpdoctorst .field-body p { + margin: 0; +} + +.phpdoctorst .line-block { + margin: 0px; +} +.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; +} diff --git a/build/composer.json b/build/composer.json new file mode 100644 index 000000000..b0facd795 --- /dev/null +++ b/build/composer.json @@ -0,0 +1,6 @@ +{ + "minimum-stability": "dev", + "require": { + "juliushaertl/phpdoc-to-rst": "dev-master" + } +} diff --git a/build/generateApiDoc.php b/build/generateApiDoc.php new file mode 100755 index 000000000..7c20a5207 --- /dev/null +++ b/build/generateApiDoc.php @@ -0,0 +1,44 @@ + + * + * @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->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', 'master']); +$apiDocBuilder->build(); + diff --git a/build/get-server-sources.sh b/build/get-server-sources.sh new file mode 100755 index 000000000..667c0574a --- /dev/null +++ b/build/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; diff --git a/developer_manual/api.rst b/developer_manual/api.rst new file mode 100644 index 000000000..632f0a0bc --- /dev/null +++ b/developer_manual/api.rst @@ -0,0 +1,25 @@ +.. only:: html + + 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 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/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