Add PHP API documentation to developer manual

[juliushaertl]

This is the first step for #509 to add a API reference to the developer manual.

For the purpose i've written a small tool called phpdoc-to-rst that will generate sphinxcontrib-phpdomain based rst files out phpDoc annotated source code.

Here is a preview of the current state:
https://bitgrid.net/~jus/nextcloud-api/com/api.html

New features:

• References to classes/methods/... are possible from within our developer manual
• Any element has a link to the source code on github.
• Each interface also shows a list of classes that implement it. This might be quite useful when you want to check how something is actually implemented.

The current state is that both lib/public/ and lib/private/ are scanned, so we can have nice linking to classes that implement interfaces from the \OCP namespace.

I welcome any feedback, especially in terms of readability.

Todo:

• Drone test for building (requires documentation: Add php, composer docker-ci#58)
• Fix some issues in the servers phpDoc comments Fix some issues in phpDoc comments server#6864

[nickvergessen]

Looks promising 😎

• Deprecation should be more prominent (is there a way to correctly link to another method? example https://bitgrid.net/~jus/nextcloud-api/com/api/OCP/Activity/IManager.html#OCP\Activity\IManager::publishActivity )
• Multi type definitions are not linked: https://bitgrid.net/~jus/nextcloud-api/com/api/OCP/Activity/IEventMerger.html#OCP\Activity\IEventMerger::mergeEvents
• Does source always link to master? Or does it link to the respective stable* branch?

[juliushaertl]

@nickvergessen Good points. The linking issue might need some fixes in sphinxcontrib-phpdomain. I'll have a look.

Does source always link to master? Or does it link to the respective stable* branch?
Right now, only to master, but of course it should link to the according branch.

[skjnldsv]

I like it a lot!!!

[juliushaertl]

Deprecation should be more prominent (is there a way to correctly link to another method? example https://bitgrid.net/~jus/nextcloud-api/com/api/OCP/Activity/IManager.html#OCP\Activity\IManager::publishActivity )

I've added styles so that deprecated methods are crossed out. The correct way according to the phpDoc reference is to add a @see tag. That one will be linked automatically. http://docs.phpdoc.org/references/phpdoc/tags/deprecated.html

Multi type definitions are not linked: https://bitgrid.net/~jus/nextcloud-api/com/api/OCP/Activity/IEventMerger.html#OCP\Activity\IEventMerger::mergeEvents

Fixed as well.

Does source always link to master? Or does it link to the respective stable* branch?

The branch can now be specified in build/generateApiDoc.php

The preview URL has been updated as well.

[skjnldsv]

So, where we at here? :)

[tflidd]

@nickvergessen can you have a look again?

[MorrisJobke]

Best would be to include "api-docs" in "all", because we also use that on our docs system deployment. 😉 Let me have a look into this.

[MorrisJobke]

Or even better: Include it in "make dev-html" ;) Then it's just at the right spot.

[MorrisJobke]

@juliushaertl Any idea regarding this:

PHP Notice:  Undefined index: opts in /drone/src/github.com/nextcloud/documentation/build/vendor/juliushaertl/phpdoc-to-rst/src/Builder/NamespaceIndexBuilder.php on line 171

[MorrisJobke]

Looks good 👍

@juliushaertl Please have a look at my commit.

[MorrisJobke]

Should we keep that task as an on-demand step or better check the computed stuff in? (like we do for the config sample as well - see https://github.com/nextcloud/documentation/commits/master/admin_manual/configuration_server/config_sample_php_parameters.rst)

[juliushaertl]

@MorrisJobke The commit looks good.

Should we keep that task as an on-demand step or better check the computed stuff in?

I see no real benefit in committing the computed files. It may lead to some confusion when people start to fix something right in the rst files, which get's overwritten later by the automated documentation generation.

PHP Notice: Undefined index: opts in /drone/src/github.com/nextcloud/documentation/build/vendor/juliushaertl/phpdoc-to-rst/src/Builder/NamespaceIndexBuilder.php on line 171

I'll have a look. juliushaertl/phpdoc-to-rst#13