FIWARE-specific documentation and Docker distribution

This project is part of FIWARE. More info on the FIWARE catalogue.

This project provides the source of various FIWARE-specific documents to AuthzForce Server. AuthzForce Server is FIWARE Authorization PDP GEri (Generic Enabler Reference Implementation):

• Technical specifications of the FIWARE Authorization PDP Generic Enabler (GE)'s API that AuthzForce implements in various forms:
  • WADL and XML schemas (the reference);
  • Apiary blueprint (the HTML output is available in Apiary style and FIWARE style ).
• The source of the GEri's documentation: Installation and Administration guide, User and Programmer Guide, etc. The generated documentation is available for each AuthzForce Server release as standalone HTML/PDF from the Server release page, or online on readthedocs.org;
• The source of the GEri's Docker image published in FIWARE Docker hub.

The actual source code of the GEri is in server component's repository.

How to generate the documentation

Checkout this git repository, go to the doc directory of the local copy, then for HTML output, run:

make clean html

For PDF output, if you do it for the first time, install the requirements (instructions for Ubuntu 14.04+):

sudo aptitude install texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra

Then run:

make clean latexpdf

Release

After any new release of AuthzForce server on authzforce/server repository, do the documentation release here as follows:

1. Update version and release variables in Sphinx configuration, to match the new AuthzForce server version.
2. Update manuals: Installation and Administration Guide and User and Programmer's Guide; especially version numbers when they occur.
3. Test the updated documentation locally:

   $ pip install -r requirements.txt
   $ make html
   

4. Update FILAB deployment scripts: install.sh, verif.sh; especially the package version to match the new AuthzForce server version.
5. Commit and push all changes
6. Re-publish the Docker image on Docker Hub from authzforce/server repository to fiware/authzforce-ce-server Docker repository.
7. Test the readthedocs.org HTML/PDF output by building the version latest from the readthedocs.org repository.
8. After the readthedocs.org build is OK, create a release on Github with same tag name as the matching release of the AuthzForce server, e.g. release-1.2.3.
9. Create a Docker tag in build settings of authzforce-ce-server's Docker repository with the new release tag as Name, e.g. release-1.2.3, save changes and trigger the build.
10. Trigger readthedocs.org to fetch the new release tag by updating something in the authzforce-ce-fiware project Settings in Admin menu such as the Description.
11. In the Versions sub-menu of Admin on this readthedocs.org repository, you should now see the new tag/version. Check the Active checkbox next to it and click Submit.
12. In the Builds menu on the readthedocs.org repository, select the new version and click the Build version: button. The build is triggered and added to the queue. Wait until the status changes to Passed.

Hotfix

If you need to fix things on a release, create a hotfix release by adding/incrementing a letter as suffix to the AuthzForce server version, e.g. 1.2.3a would be the first documentation fix for AuthzForce version 1.2.3 (the tag would be release-1.2.3a), 1.2.3b would be the second hotfix, etc.