PHPackages daniel-ac-martin/apidoc - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. daniel-ac-martin/apidoc ActiveProject[API Development](/categories/api) daniel-ac-martin/apidoc ======================= A system for creating API reference documentation. 0.2.0(11y ago)0702GNU GPLXSLT Since Jan 20Pushed 11y ago1 watchersCompare [ Source](https://github.com/daniel-ac-martin/apidoc)[ Packagist](https://packagist.org/packages/daniel-ac-martin/apidoc)[ Docs](https://github.com/daniel-ac-martin/apidoc)[ RSS](/packages/daniel-ac-martin-apidoc/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)DependenciesVersions (5)Used By (2) apidoc ====== [](#apidoc) A system for generating API reference documentation from a collection of XML files. Rationale --------- [](#rationale) API documentation matters. The quality of a software library's documentation has a great effect on the speed at which a prospective programmer can start using it, and that speed greatly affects whether the library will be used at all. At present there are two main approaches to producing API documentation. The first is to simply write it manually as you would the rest of your project's documentation. The other is to insert specially formatted comments directly into your project's source and to generate documentation from this. (Examples include Doxygen, javadoc and PHPDocumentor.) In my opinion, both of these approaches are quite flawed. In the first approach it is very easy for mistakes in the API specification to not be picked up. This is because general documentation formats are not designed to deal with programming APIs, which must be very strictly defined. Also, it is very easy for programmers to change the API in the source code whilst forgetting to update the documentation. In the case of in-line documentation, there is the ugly situation of having two separate syntaxes mixed in a single file. The rationale is that the programmer should update the documentation at the same time he changes the source code but again, there is no guarantee of this. The benefit this offers over the first approach is that the API is at least strictly defined, though it may still become outdated. Intermingling API documentation with source code generally causes at least one of the following problems: 1. The source code becomes much harder to read as considerable screen space is given over to the documentation comments. 2. The API is insufficiently documented as the programmer attempts minimise the pollution of his source code. i.e. In-line documentation is an excuse for hardly documenting at all. Additionally, in-line documentation can encourage a lack of proper traditional commenting of source code. - Comments that are useful to the programmer working on the library itself are very different in nature from API documentation. Instead, I propose an alternative. Rather than loosely defining APIs in the main documentation or strictly defining them in a second syntax in our source code, we can maintain a set of API documentation files adjacent to our source code files and strictly define our API in those. e.g. ``` project/src/some_file.php # Some source code file project/src/some_file.xml # The strict specification of the API along with # documentation ``` Alternatively, one could provide a separate directory for the purpose in the same way many people separate off their unit tests from their main source code. e.g. ``` project/src/some_file.php # Some source code file project/src-doc/some_file.xml # The strict specification of the API along # with documentation ``` This approach has the following advantages: 1. The API documentation can use its own strictly defined syntax ensuring that the specification is valid. 2. Source code syntax and documentation syntax are no longer mixed in the same files. Source code can be beautiful and concise again with comments that are actually helpful. 3. Conformance with the documentation can be tested for in the unit tests. (Most general purpose programming languages have libraries for reading XML files.) This makes it far easier to ensure that the documentation is correct. The initial implementation -------------------------- [](#the-initial-implementation) This project is the initial implementation of the idea. I am using it to document a library I have written in PHP. (Though the system should work just as well for many other languages.) It works well for my purposes but I should stress that it has been hacked together using mainly XSLT and GNU Bash. i.e. It is not the most elegant implementation imaginable. I suspect it will only run on GNU/Linux systems, though it might be possible to use it on other \*nix systems and Cygwin environments. The main requirements are: 1. GNU Bash 2. xmllint (libxml) 3. xsltproc (libxml) It compiles the source documentation to another documentation format so that it can be incorporated into the project's main documentation. At the time of writing the only format supported is the Docbook format used by PhD (which is what is used to generate php.net). Installation ------------ [](#installation) Besides checking out the code through git. It is possible to install it through composer by running the following commands from your project's main directory: ``` php ./path/to/composer.phar require daniel-ac-martin/apidoc php ./path/to/composer.phar install ``` apidoc can then be run by typing: ``` vendor/bin/apidoc ``` Usage ----- [](#usage) The main script file, apidoc, is a bash script. Full usage information is available by executing "apidoc -h". Generally one creates an XML file called "apidoc.xml" in the root directory of your project from which apidoc takes it's information. (Alternatively the program can be called with the information provided through the programs arguments.) Here is an example of the configuration file: ``` src-doc build/doc ``` This will look for source files in the src-doc/ directory that end with ".xml". It will then collate them and then transform them using the template called "phpnet" (the only valid template at the time of writing). The transformed files (including any intermediate steps) will then be placed in the build/doc/ directory. The user can then insert the resulting API documentation into their project's main documentation. License ------- [](#license) Copyright (C) 2015 Daniel A.C. Martin Distributed under the GNU General Public License v3 or any later version. ### Health Score 26 — LowBetter than 43% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity8 Limited adoption so far Community11 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~29 days Total 4 Last Release 4040d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7e3a2c497789367a1c1ebc65fecd4e0fdd3b6ed22af78a779f5aa6e33c660993?d=identicon)[daniel-ac-martin](/maintainers/daniel-ac-martin) --- Top Contributors [![daniel-ac-martin](https://avatars.githubusercontent.com/u/10604229?v=4)](https://github.com/daniel-ac-martin "daniel-ac-martin (29 commits)") --- Tags apidocumentationgeneratordocdocsapidocapi-doc ### Embed Badge ![Health badge](/badges/daniel-ac-martin-apidoc/health.svg) ``` [![Health](https://phpackages.com/badges/daniel-ac-martin-apidoc/health.svg)](https://phpackages.com/packages/daniel-ac-martin-apidoc) ``` ### Alternatives [binarytorch/larecipe Generate gorgeous recipes for your Laravel applications using MarkDown 2.5k2.7M16](/packages/binarytorch-larecipe)[apigen/apigen PHP source code API generator. 2.2k627.9k223](/packages/apigen-apigen)[crada/php-apidoc Generate documentation for php API based application. No dependency. No framework required. 259206.9k2](/packages/crada-php-apidoc)[unionofrad/li3_docs An API and wiki-like documentation generator. 1682.6k](/packages/unionofrad-li3-docs)[yaro/apidocs Api documentation generator for Laravel 5 114.1k](/packages/yaro-apidocs) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)