Merge pull request #578 from nextcloud/api-doc

Add PHP API documentation to developer manual

.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
+

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/

_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;
+}

build/composer.json

@@ -0,0 +1,6 @@
+{
+    "minimum-stability": "dev",
+    "require": {
+        "juliushaertl/phpdoc-to-rst": "dev-master"
+    }
+}

build/generateApiDoc.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * @copyright Copyright (c) 2017 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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 <http://www.gnu.org/licenses/>.
+ *
+ */
+
+/*
+ * 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();
+

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;

developer_manual/api.rst

@@ -0,0 +1,25 @@
+.. only:: html
+
+    API Documentation
+    =================
+
+
+    PHP public API
+    --------------
+    .. toctree::
+        :maxdepth: 1
+
+        /OCP namespace <api/OCP/index>
+
+
+    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 <api/index>
+        /OC namespace <api/OC/index>

developer_manual/index.rst

@@ -22,3 +22,4 @@ Table of contents
     core/index
     bugtracker/index
     commun/index
+    api

requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinxcontrib-phpdomain
+rst2pdf
+pillow