Creating a Source Code Documentation for your own OXID Project

Of course you are aware of the source code documentation for OXID eShop we publish for every single version/patch release of the Community Edition – maybe you even know it by heart.

So you created your own project based on the Community Edition, possibly even an extension you want to share with others in the OXID community.
Would it not be grand to to automatically generate the documentation likewise, no matter what OXID eShop edition is used?

Intrigued to know how it works, aren’t you. Let’s have a look at the requirements and steps involved, it’s no rocket science 😉

Prerequisites

Please take a look at Marco’s Blogpost about assembling a local dev environment with oxVM vagrant box. Depending on your operating system as host, you might want to choose different ways to install

  • doxygen (please make sure your installation is >= version 1.8.10 if you want to document your entire project/different folders) and
  • the package graphviz:

either on your host system with a direct access to your shared folder or on the guest VM (AKA oxVM). Once the vagrant box is started via vagrant up you can use vagrant ssh to connect and follow the instructions on this README.md file to install graphviz and doxygen. We’ve already planned to have these packages installed and ready to run from within oxVM vagrant box by default. With perseverance, this will be accomplished in the near future.

Off we go – an example how to do it with V6

Going forward from V6 the supported installation method has been changed. Unfortunately this is not yet reflected in the VM, so when installing oxVM with vagrant up, OXID eShop will presently be installed via git clone, that’s why you will not find the directory vendor/oxid-esales/oxideshop_ce in it (will be changed in the near future). However, for the full source code documentation it is necessary to have this folder in your oxVM. Please install OXID eShop as a new composer project with this command inside your oxVM:

Check out the repository ox_doxygen or download the zip file and place generateSourceCodeDocumentation.sh as well as doxy.conf.template above your document root (my_oxid_eshop_project/source). It shall now look like that:

Make sure the bash script generateSourceCodeDocumentation.sh is executable:

This bash script is using the values in doxy.conf.template which of course can be adapted to your personal needs. For the purposes of this example keep the preconfigured settings. Later when you are comfortable with using the tool go ahead and play around with the settings. For generateSourceCodeDocumentation.sh we have to provide the four parameters -e (for edition), -v (for version) -i (input directory or directories) as well as -o (output directory).

Hint: You can also place generateSourceCodeDocumentation.sh and doxy.conf.template in a separate location, run it from there and use absolute path locations for -i and -o.

Open a terminal in this folder and type

Enter and generate! This bash script will now create a searchable HTML source code documentation including all of your alterations plus modules and extensions. In other words, it will document all of your source code including modules you chose in the command above as long as you provide PHP doc header blocks as outlined in the doxygen manual here. Examples more tailored to PHP are available from the PEAR documentation.

If you have followed the setup example from Marco’s Blogpost about assembling a local dev environment with oxVM vagrant box you can easily access it via browser at http://projects.dev/my_oxid_eshop_project/docs/. But if you have followed the established setup procedure from the OXID oxvm_eshop repository the default shop is set up at http://oxideshop.dev/ and will not provide means to access your freshly generated docs out of the box. Normally you will use it on /var/www/oxideshop, but when you start using your own adapted environment there are many ways to make it accessible. For the sake of this example lets keep it simple, just do

Now you can access the generated output at http://oxideshop.dev/docs/.

OXID source code documentation with Doxygen

Attention: In case you’re generating your source code documentation for commercial products like OXID eShop Enterprise and Professional Edition or proprietary modules/extensions, please take care this source code documentation will not be publicly available.

For questions or feedback go ahead and comment in this blog post.

 

4.00 avg. rating (80% score) - 4 votes


0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *