Our User Support team has been working on very exciting changes that will make AIMMS documentation a lot easier to find and navigate through. One of those changes has been the transformation of the AIMMS Function Reference from a PDF into an HTML site. This is a pretty big deal for us. Not just because the Function Reference is now more seamless to use, but because we achieved this using a template that you can use to build your own AIMMS documentation site too! We have open-sourced the theme files in GitLab. Read on to find out what got us here and why we’re so thrilled to share this with you. 

First, a word about the AIMMS Function Reference  

The AIMMS Function Reference is the go-to guide for all the functions, sets, and procedures in the AIMMS core. They are the pre-declared building blocks of the AIMMS language. When we first started out, these got documented in a PDF. That PDF grew over the years and, as you can imagine, it became quite long and difficult to maintain. So, we embarked on a project to turn hundreds of pages in the PDF into an HTML website.  

We decided to build a Python script to convert Latex (the language we use to generate the PDF) into the RST syntax we are using for all our docs. This script allowed us to migrate the content to an HTML page efficiently, and the best thing is we will be able to re-use it to convert all other PDF in our documentation, like the AIMMS Language Reference, the User Guide and more.  

Besides the script, we developed a website theme with all the CSS, HTML and related technicalities surrounding our docs framework. This theme, which is based on the Sphinx Python Technology, is now available for anyone to use on GitLab.  

What’s new and better?  

With our new Sphinx website, the AIMMS Function Reference is now more easily crawled by Google. This means that if you search for a specific topic found in the document on Google, for example, you’ll be able to locate it on the Function Reference a lot faster. Instead of getting a link to the PDF, you’ll get a link to the exact location of the search term.  

The styling is a lot nicer and more in line with the rest of our web properties. Most importantly, you can now navigate through the reference a lot more easily and access links to all related documentation. You’ll notice we have been able to use the extra widgets we have enabled in our latest docs, like the help add-on that links to conversations and help topics in our community, and our new search functionality powered by Algolia. In short, browsing and finding the docs you need is now a lot easier. 

Using the Theme as a Framework to Document your AIMMS Project  

Many AIMMS developers document the ins and outs of their AIMMS project for colleagues and future generations of developers who come to their organization. You want others to be able to understand what happens in your model and what different procedures are doing. You can now use our Sphinx theme to generate these docs in a nicely formatted HTML website that you can publish publicly, in your own network or even within your project files! It’s a great way to hand over the model for maintenance and improvements or make your model documentation easy to use for everyone involved. Visit the GitLab website to learn more.  

There’s more to come 

As we mentioned earlier, we are using the same framework for all other PDFs in our docs repository. You can expect the User Guide, Language Reference, AIMMS PRO API docs and many other PDFs to be migrated in the coming months.  

Besides rolling out these docs in the new HTML format, we are developing a script to convert an AIMMS model into RST syntax.  This will allow us (and you) to automatically build a documentation website from any AIMMS model. It’s a script that transforms the AIMMS textual representation into an HTML representation. We’re packaging this up for our users and will update you in our Community when it becomes available. So, stay tuned!   

We hope you have fun with our new Sphinx theme and find it as handy as we do to release your AIMMS documentation. Drop us a line in the comments if you have feedback or questions 

Our colleague Wouter Bouma is certainly celebrating the release of our Sphinx theme