PHP Classes

How to Generate PHP Documentation from Comments in PHPDoc Format to Create a Github Wiki - PHPDoc 2 Github Wiki package blog

Recommend this page to a friend!
  All package blogs All package blogs   PHPDoc 2 Github Wiki PHPDoc 2 Github Wiki   Blog PHPDoc 2 Github Wiki package blog   RSS 1.0 feed RSS 2.0 feed   Blog How to Generate PHP D...  
  Post a comment Post a comment   See comments See comments (2)   Trackbacks (0)  

Author:

Viewers: 453

Last month viewers: 3

Package: PHPDoc 2 Github Wiki

Github Wikis provide a means to create documentation for a package in a simple way. This way, developers can update documentation easily while the versions of documentation wiki are maintained also in Git repository.

Read this article to learn how to create documentation automatically for your PHP packages using phpDocumentor and then have that documentation updated in a Github wiki.




Loaded Article

In this article you will learn about:


Create a Github wiki for your repository

Open the repository you want to create a wiki for on https://github.com and navigate to the wiki page:

Create github wiki

To set up the wiki we have to create the first page inside our repository:

Welcome to github wiki

A Github wiki for a repository is nothing other than a special repository that can be accessed with desktop tools as well. The name of this repository corresponds to the name of the main repository with the extension .wiki

Repository: https://github.com/Stefanius67/phpdoc2githubwiki
Wiki:       https://github.com/Stefanius67/phpdoc2githubwiki.wiki

Unfortunately, the current Github desktop app comes up with error 'Sorry, I can't find any repository matching ...' when trying to clone a Github wiki. So we have to clone it from the command line:

  1. create subdirectory 'wiki' (or any other prefered name...) on your local machine
    mkdir wiki
  2. If this directory is inside the local path of the repository, the wiki is for, don't forget to add the created wiki-repository directory (here <mypath>/phpdoc2githubwiki/wiki/phpdoc2githubwiki.wiki) to the .gitignore file.
  3. change to the directory
    cd wiki
  4. clone the wiki with following command:
    git clone https://github.com/Stefanius67/phpdoc2githubwiki.wiki

After cloned it once, we can open the github desktop app and add the repository with File - add local repository. From now we can perform any operations (fetch, commit, pull, push,...) within the App.

Github desktop app

Example Wiki

An example for a Github wiki that contains an auto generated class reference can be found on Stefanius67/Formgenerator/wiki.

The structure of a Github wiki

Although github-wiki supports other formats, I will only deal with the Markdwon format at this point, as this format is generated with the phpDocumentor template that is used here.

All pages displayed in the wiki are located in the root of the wiki-repository!

Note:
Although Github-wiki also finds documents in subdirectories, it is not recommended to work with a directory structure because Github-wiki resolves internal links both within the documents and in the sidebar directly to the root directory.
In addition, documents with the same name in different folders are always brought to the first document found (also in the 'Pages' list)

the file name of a document is also the heading of the respective page, whereby spaces in the title are represented by '-' characters in the file name and the file-extension is supressed.

A wiki can contain three special files:

  1. Home.md: the Starting Page of the wiki.
    This is the page created, when setup a wiki.
  2. _Sidebar.md: a user defined sidebar.
    Can be created manualy in the wiki-repository or from the wiki page on https://github.com: ([+ Add a custom sidebar] on the right of the wiki-page
  3. _Footer.md: A user defined footer.
    Can be created manualy in the wiki-repository or from the wiki page on https://github.com: ([+ Add a custom footer] on the bottom of the wiki-page

All files in the root of the wiki-repository in a supported format will be listed in alphabetical order in the Pages pane on the right of the wiki. As soon as a user-specific sidebar has been defined, the Pages pane is collapsed by default.

References inside the wiki

To build a references inside a document to another page in the wiki just use the title of that page ('-' instead of spaces but don't use any extension):

[A Special description](./A-Special-description)

will output a link with the text 'A Special description' and the href A-Special-description.md. This referencing can also be used in the _Sidebar.md.

Reference to an anchor

The Github Markdown parser automatically creates an anchor for each heading (independent from the level) consists of the header text in lowercase where spaces replaced by a '-' sign. Thus, it is possible to insert a link to a header in the same document like following:

[Header on the same page](#header-on-the-same-page)

This will result in a link to the header 'Header on the same page' in the current Document.

The same mechanism works to link to an anchor on another page of the wiki:

[Header on the other page](./The-other-page#header-on-the-other-page)

Note that the file extension must also be omitted here!

Keep always in mind:
Changing the title of a wiki page or a heading within a page can lead to broken links, but unfortunately there is no automatic method to search the wiki for broken links.

Embedding of graphics in a wiki page

In principle, graphics from any absolute source can be included, but it is more interesting to include graphics that are part of the documentation.

Best practice to do so will be, to create any subfolder (e.g. 'images') inside of the wiki-repository and put all images in this location. The associated markdown should then look like this:

![image1](./images/MyFirstImage.png)

Store or cache the Github credentials

When using the builder or the script to publish the wiki, Git will need the GitHub credentials from the user in order to perform the push operation.

Important:
For security reasons, GitHub is deprecating the username and password authentication method in November 2020. Read more from GitHub about deprecating password authentication.

Since the login with access token in the command line is very cumbersome (the token is a long complex string of characters ...) I recommend using the 'Git-Credential-Manager-Core' component to log in simplify.

On windows systems

Download the lates version from here and just install it. You will be asked once to login (you can do this using the webbrowser and your 'normal' login credentials or directly using your username and your access token).

On Linux systems

Download the gcmcore-linux_amd64.x.x.xxxx.deb from here and execute following commands from the directory the file is located:

sudo apt install ./<filename>.deb
git-credential-manager-core configure
git config --global credential.credentialStore cache

When calling a git command that requires a login, the GitHub login is requested by the Credential Manager. Here, too, you can choose between the two variants (via the web browser or using an access token).

The third line instructs the Credential Manager to temporarily store the access data in the gib internal cache. After the set time (default 900 sec.) has elapsed, the cache is cleared automatically and you have to log in again. To change the timeout use (XXX: seconds for the timeout):

git config --global credential.cacheOptions --timeout XXX

Alternatively, the credentials can be saved permanently if the option plaintext is selected instead of cache

git config --global credential.credentialStore plaintext

Since the access data is stored as readable text on the system with this method, everyone should decide for themselves whether they want this or not (this should primarily depend on who has access to the system ...)

List of possible memory types under Linux and more detailed explanations.

Install phpDocumentor 3

The template needs phpDocumentor Version 3, which has been completly redesigned and now uses the TWIG template engine. This engine allows users to write their own templates much easier than the version(s) before.

Install the version

  1. Download phpDocumentor.phar file from https://github.com/phpDocumentor/phpDocumentor/releases/tag/v3.0.0. (scroll to the end of the section and open the 'assets'). A newer version may can be used but isn't tested with this template so far.
  2. Make the phar accessible from anywhere:
    • On a linux machine (suggested path for Ubuntu - other distributions may differ in the path):
      • Move the PHAR file to a system wide accessible directory (a directory contained in the system path - e.g. /usr/local/bin):
        sudo mv phpDocumentor.phar /usr/local/bin/phpDocumentor
      • Ensure, the file is executable:
        sudo chmod +x phpDocumentor
      • If necessary, you can rename the file in order to shorten the call or to be able to run different versions on the same machine (e.g. phpdoc30).
  3. On a windows machine:
    • Move the file to any decided folder.
    • Create the batch file phpDocumentor.bat in that folder with following content:
      @echo off
      php %~dp0phpDocumentor.phar %*  
    • Add the folder to the system path.
  4. Now you should be able to call the phpDocumentor from any directory on your system.

Install and use the GitHubWiki builder

Install the builder

  1. Download the latest version of the githubwiki.phar
  2. Make the phar accessible from anywhere:
    • On a linux machine (suggested path for Ubuntu - other distributions may differ in the path):
      • Move the PHAR file to a system wide accessible directory (a directory contained in the system path - e.g. /usr/local/bin):
        sudo mv githubwiki.phar /usr/local/bin/githubwiki
      • Ensure, the file is executable:
        sudo chmod +x githubwiki
    • On a Windows machine:
      • Move the file to any decided folder.
      • Create the batch file githubwiki.bat in that folder with following content:
        @echo off
        php %~dp0githubwiki.phar %*  
      • Add the folder to the system path.
  3. The builder is now available in the command line from anywhere in the system via githubwiki [options].

Using the builder

The builder can be executet from the root of your project by calling githubwiki [options]:

OptionDescription
--config [path]Alternative configuration file
--title [text]Title of the wiki
--phpdoc [command]The command to launch phpDocumentor
--wiki [path]The path to the wik
--help -hDisplay this help message
--quiet -qDo not output any message
--verbose -vMore detailed output

Note:
All command line options can also be specified in the configuration file.
Command line arguments overwrite settings from the configuration file!

Alternative configuration file

If no config file is specified, the builder searches for githubwiki.xmml in the current working directory. If that file dosn't exist, only command line arguments and default values are used.

The configuration file

Within the XML configuration file for the builder all options (including the configuration for phpDocumentor) can be specified.

<?xml version="1.0" encoding="UTF-8" ?>
<githubwiki>
    <!-- Title of the wiki to create -->
    <title>Title of my wiki</title>

    <!-- some options for the builder -->
    <options>
        <quiet>false</quiet>
        <verbose>true</verbose>
    </options>
    
    <!-- general settings for phpDocumentor -->
    <phpdoc>
        <command>phpdoc30</command>
        <config>MyPhpDoc.xml</config>
        <template>Path-to-my-template</template>
    </phpdoc>

    <!-- path settings -->
    <paths>
        <output>Path-to-my-wiki</output>
        <cache>Path-to-create-cache</cache>
        <project>Path-to-the-project-files</project>
    </paths>
    
    <!-- source files to be scaned -->
    <source>
        <path>[First File or directory to scan]</path>
        <path>[Second File or directory to scan]</path>
        <path>[...]</path>
        <path>[n-th File or directory to scan]</path>
    </source>

    <!-- Content/scope of the wiki to be generated -->
    <visibilities>
        <visibility>public</visibility>
    </visibilities>            
    
    <!-- docblock tags to be ignored -->
    <ignore-tags>
        <ignore-tag>author</ignore-tag>
        <ignore-tag>version</ignore-tag>
        <ignore-tag>copyright</ignore-tag>
        <ignore-tag>codeCoverageIgnore</ignore-tag>
    </ignore-tags>
</githubwiki>

Title of the wiki

Specify the title that is used inside the generated class reference. If the title is specified in the command line and contain blanks you have to set it into double quotes.

General settings for phpDocumentor 

The command to launch phpDocumentor

If the phpDocumentor.phar was renamed during the installation, this changed name must be set here.

(default value: phpDocumentor.phar)

External phpDocumentor configuration

In normal use (config is empty or missing), the builder creates a configuration file for the phpDocumentor based on its own configuration settings in the cache path. If special settings are required for the phpDocumentor, an external file can be specified here, which will be used instead of the automatically generated file. All further information on the project source files to scan, the visibility and the tags to be ignored that are specified in the configuration for the builder are thus ignored!

The value can contain any path absolute or relative to the working directory.

External phpDocumentor template

In normal use (templateis empty or missing), the builder creates the latest template in the cache path. If you have made some modifications to this template an external can be specified here. The path can be absolute or relative to the working directory.

Path settings 

The path to the wiki

The path where the wiki is located. (see Create a Github wiki for your repository). This path can be absolute or relative to the current working directory.

Cache path

Both phpDocumentor and the GitHubWiki builder create some temporary files wherefore a path must be specified. Default value is 'cache' in the current working directory. If the folder doesn't exist, the builder try to create it.

Keep in mind:
If this path is located inside your project directory, don't forget to add it to your .gitignore file!

Project path

The base path where all PHP source files to scan are located. If the builder is run from the root of your project just leave this path empty!

The following information in the source section relates to this path.

Source files to be scaned

Any number of directories or files either with absolute path information or relative to the project path. This list is passed to the phpDocumentor. If an external configuration file was specified for the phpDocumentor, these settings will be ignored!

Content/scope of the wiki to be generated

In this section you can control which phpDoc elements should be included in the wiki. This generally depends on the target group the wiki is aimed at.

For users of the project the settings public and/or api are most useful, is it aimed to other programmers, it usually make sense to in addition to include protected or further levels (private, internal, hidden).

Docblock tags to be ignored

Speccify the docBlock tags that should be ignored. This can be any number of tags.

Using the template with bash script

  1. Download the ZIP of the githubwiki package and extract it to any folder on your system.
  2. Copy the script githubwiki and the phpDocumentor config file phpdoc.xml from the bash directory to the folder where you have cloned the wiki-repository.
    NOT in the root of the wiki-repository!
  3. Adapt the phpdoc.xml configuration file.
  4. Adapt the githubwiki bash script.

phpDocumentor configuration

Th phpdoc.xml is the phpDocumentor configuration file to generate the documentation.

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor
        configVersion="3"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://www.phpdoc.org"
        xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd">

    <!-- title of your wiki/package -->
    <title>Formgenerator</title>
    <paths>
        <!-- root of the wiki repository -->
        <output>./[Projectname].wiki</output>
        <cache>./cache</cache>
    </paths>
    <version number="latest">
        <api>
            <!-- all source files to scan -->
            <source dsn="[Base path to the project]">
                <path>[First File or directory to scan]</path>
                <path>[Second File or directory to scan]</path>
                <path>[...]</path>
                <path>[N-th File or directory to scan]</path>
            </source>

            <!-- 
                Setup the visibility level you want your documentation for 
                 - multiple levels can be specified
            -->
            <visibility>public</visibility>
            <!-- <visibility>api</visibility> -->
            <!-- <visibility>protected</visibility> -->
            <!-- <visibility>private</visibility> -->
            <!-- <visibility>internal</visibility> -->
            <!-- <visibility>hidden</visibility> -->

            <!-- 
                Setup the tags that shoud be ignored while scaning source code
                - multiple tags can be specified
            -->
            <ignore-tags>
                <ignore-tag>author</ignore-tag>
                <ignore-tag>version</ignore-tag>
                <ignore-tag>copyright</ignore-tag>
                <ignore-tag>codeCoverageIgnore</ignore-tag>
            </ignore-tags>
        </api>
    </version>
    <!-- the path to the template from the phpdoc2githubwiki repository -->
    <template name="[path-to-phpdoc2githubwiki-repository]/template"/>
</phpdocumentor>

It must be supplemented as follows:

  1. <title>
    The title for the wiki
  2. <paths><output>
    Replace [Projectname] with the name of your repository.
  3. <paths><cache>
    The setting for the cache directory can be retained. In this case, however, it is strongly recommended to include this directory (/ wiki / cache /) in the .gitignore of the main repository as well. Alternatively, a path outside of the repository can be specified here.
  4. <version><api><source>
    In the <source> tag you must specify the base path of the source code to scan with the dsn attribute. This Path can be absolute (recommended) or relative to the directory, the config file is located.
  5. <version><api><source><path>
    Inside of the <source> tag you can specify any number of <path> tags that contain either a directory or a filepath to catch all sourcefiles that should be scaned for the documentation. This entries are relative to the specified base path.
  6. <version><api><visibility>
    Multiple visibility levels can be specified, depending on the target group for which this documentation is intended.
  7. <version><api><ignore-tags>
    Any number of tags can be specified that should be ignored during scanning.
  8. <template>
    The full path to the template (path where you have extracted this repository followed by /template) have to be specified in the name attribute of this element.

A more detailed explanation of this xml based file can be found at docs.phpdoc.org.

Script configuration

The bash script githubwiki can be used to build the wiki calling phpDocumentor and to publish the builded files on www.github.com using the git command line tools

To do so, there also have to been made some supplementations:

#!/bin/bash
# The command to call phpDocumentor 3 (see readme.md / wiki for more information)
phpdoccmd='[Name of the phpDocumentor command]'
# the path to the git wiki repository
wikidir='[path to the local git wiki repository]'

...
  1. phpdoccmd='[Name of the phpDocumentor command]'
    Specify the command to run the phpDocumentor. (See Install phpDocumentor 3)
  2. wikidir='[path to the local git wiki repository]'
    The root directory of the wiki repository is required to call the Git command line tools. This can be specified either relative to the current path or absolutely.

Usage of the script

The script can either be called with following parameter:

  • bash githubwiki -s (or -sync) to sync the local repo with the remote bofore build
  • bash githubwiki -b (or -build) build the wiki markdown using phpDocumentor
  • bash githubwiki -p (or -publish) publish the wiki
  • bash githubwiki -a (or -all) perform the sync, build and publish steps in one call

Important:
A pull request is carried out before publishing, but if manual changes have been made in the wiki direct on 
www.github.com since the last publication with the script, it is advisable to use Github desktop to synchronize the local repository and the wiki repository in order to avoid problems when merging.

For more information about using the git command line tools can be found on getting started with git and using git

Additional hints

Here are some additional hints to help you create, edit and maintain your wiki.

Files created by phpDocumentor

As already explained under 'The structure of a Github wiki', all wiki pages should be located in the root of the repository. In accordance with this specification, all files that are created using this template are placed there.

The following files are created:

  • Class--Reference.md
    The Overview page for the class reference. It contains the overview of all classes, traits and interfaces with the respective short description broken down according to the existing namespaces.
  • Class--Reference-Sidebar.md
    A template containing a short version of the overview that can be used in the custom sidebar of your wiki.
    The _Sidebar.md file is deliberately not created, as it may already contain manual extensions to possibly existing, supplementary wiki pages.
    (see Create a custom sidebar for more information)
  • Class-*.mdTrait-*.mdInterface-*.md
    For each class, trait and interface a document is created with its own name and the corresponding prefix. Within a wiki, a class with the same name must not appear in different namespaces, as these would overwrite each other (the namespace is not part of the file name).
  • _Footer.md
    The custom footer. If you have defined a own custom footer, you can prevent the generation of this file by deleting the marked line in the template.xml file in the template directory:
         ...
         <transformation writer="twig" source="sidebar.md.twig" artifact="Class--Reference-Sidebar.md"/>
    -->  <transformation writer="twig" source="footer.md.twig" artifact="_Footer.md"/>
         <transformation writer="twig" query="indexes.classes" source="class.md.twig" artifact="Class-{{Name}}.md"/>
         ...

Recommendation:
To avoid confusion or overlap between automatically generated and manually generated pages, do not manually create a page with a title that begins with "Class ", "Trait ", or "Interface ".

Create a custom sidebar

In order to be able to navigate comfortably and clearly within the wiki, it is advisable to create a custom sidebar. In contrast to the standard 'Pages' pane at the top right (in which all pages are listed alphabetically), a custom sidebar allows you to determine the structure, order and content yourself. To avoid overwriting an existing sidebar, only a template (Class--Reference-Sidebar.md) is created that contains the overview in a nested list. To use this, the part you want can simply be copied from the template file to the _Sidebar.md file (Or just rename the template, if no custom sidebar has been created so far).

Any links to other pages (or to certain anchors there) can be inserted in the manually created part of the sidebar. See References inside the wiki for more information.

Images from the source code docBlock

A description can often be made much more understandable or clearer by adding an image.

As an extension of the phpDoc standard, this template supports the insertion of images within a class docBlock using an custom tag.

/**
 * This is the summary of myClass.
 *
 * Followed by a more detailed description
 * of multiple lines...
 *
 * @SKienImage myClassImage.png
 */
class myClass
{
}

Using the tag @SkienImage followed by the filename (without directory) will insert the specified image after the class description. The image must be in the subdirectory images of the wiki repository.

(see Embedding of graphics in a wiki-page)

Download or Install PHPDoc 2 Github Wiki Using PHP Composer

The PHPDoc 2 Github Wiki package can be downloaded from download page or be installed using the PHP Composer tool following instructions in the Composer install instructions page.




You need to be a registered user or login to post a comment

Login Immediately with your account on:



Comments:

1. very nice article - José Filipe Lopes Santos (2021-08-02 09:38)
very nice article... - 1 reply
Read the whole comment and replies



  Post a comment Post a comment   See comments See comments (2)   Trackbacks (0)  
  All package blogs All package blogs   PHPDoc 2 Github Wiki PHPDoc 2 Github Wiki   Blog PHPDoc 2 Github Wiki package blog   RSS 1.0 feed RSS 2.0 feed   Blog How to Generate PHP D...