sphinx-aimms-theme

AIMMS theme for Sphinx


License
MIT
Install
pip install sphinx-aimms-theme==0.1.28

Documentation

sphinx-aimms-theme

This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devices for AIMMS projects and libraries.

This theme also includes:

Please find the documentation of those 2 elements following the links above.

This theme is inherited from the great Read the Docs but can work with any Sphinx project.

You can find a working demo of the theme on AIMMS documentation websites:

Installation

This theme is distributed on PyPI and can be installed with pip.

Because it's inheriting some features from Read the Docs theme, you will need to install it as well. You may run the following 2 commands to install it:

pip install sphinx-rtd-theme

pip install sphinx-aimms-theme

To use the theme in your Sphinx project, you will need to add the following to your conf.py file:

extensions = [
    ...
    "sphinx_aimms_theme",
]

html_theme = "sphinx_aimms_theme"

Configuration

Theme options

The following options can be defined in your project’s conf.py file, using the html_theme_options configuration option.

For example:

html_theme_options = {
    'doc_title': 'Title of my docs',
    'home_page_description': 'my meta description',
}

(if not specified, the option is a string)

  • doc_title

    Title you will see on the top left corner of your docs

  • home_page_title

    HTML Title that will appear in the html meta title of your home page

  • home_page_description

    Description that will appear in the html meta description of your home page

  • display_community_help_link

    Boolean - Displays a link at the bottom of every article redirecting to the AIMMS community search page filled with the title of the current page.

  • display_community_embeddable

    Boolean - Displays an embbedable from the AIMMS Community, showing topics filtered with the title of the current page

    Send an email to support@aimms.com if you would like to activate the community embeddable on your docs.

  • display_local_toc

    Boolean - Displays a dynamic local table of content for each file, except top index files.

  • generate_google_analytics

    Boolean - generates a google analytics HTML code as follows on every page:

        
        <script async src="https://www.googletagmanager.com/gtag/js?id={{ google_analytics_id }}"></script>
        <script>
            window.dataLayer = window.dataLayer || [];
        
            function gtag() {
                dataLayer.push(arguments);
            }
            gtag('js', new Date());
        
            gtag('config', '{{ google_analytics_id }}');
        </script>
        
    

    Where google_analytics_id is the following option

  • google_analytics_id

    Change the Google Analytics ID that is included on every page

  • display_algolia_search

    Replace the current default search box with an Algolia extension. You must have registered your docs website on https://community.algolia.com/docsearch/#join-docsearch-program, and thus obtain from Algolia the following 3 options:

  • algolia_appid

  • algolia_appkey

  • algolia_indexname

  • algolia_hitsperpage

    Set the number of items shown in algolia's search result dropdown

Theme source code

The theme source code can be found in your Python installation folder, at PythonXX\Lib\site-packages\sphinx_aimms_theme.

You may customize (overwrite) locally parts of it via "templating", as described here

Home Page

Some CSS code is shipped together with the theme to customize your home page "boxes", as you can see on AIMMS How-to or AIMMS Documentation.

You may (or not) use it to show your own topics. To help you customize it, please see the RST source code of the How-to Home page below:


.. image:: Images/rocket-32.png
   :scale: 0

.. image:: Images/school-supplies-32.png
   :scale: 0

.. image:: Images/time-machine-32.png
   :scale: 0

.. image:: Images/global-chain-32.png
   :scale: 0

.. image:: Images/web-design-32.png
   :scale: 0

.. image:: Images/network-care-32.png
   :scale: 0

.. raw:: html
    
    <h1 class="home_header">WELCOME TO HOW-TO</h1>
    
.. raw:: html
    
    <div id="content_home_page">

        <p>AIMMS How-To is a knowledge base for everyone involved in projects that use AIMMS, including developers, network administrators, application end-users, and business process stakeholders.</p>
        <p>You'll find tutorials, best practices, and practical guidance for using AIMMS software, including help topics in mathematical modeling, solvers, AIMMS language, and building applications in optimization and prescriptive analytics. You'll also find support for troubleshooting errors and handling deprecations.</p>

        <div class="boxes">
            <a class="box_home_page" href="C_Getting_Started/index.html">
                <img alt="getting started" src="_images/rocket-32.png">
                <h1>Getting Started</h1>
                <div>Installing AIMMS, settings options, licensing help</div>
            </a>
            <a class="box_home_page" href="C_Developer/index.html">
                <img alt="developer" src="_images/school-supplies-32.png">
                <h1>AIMMS Developer</h1>
                <div>Data connection, modeling, solvers, programming, error handling</div>
            </a>
            <a class="box_home_page" href="C_UI/index.html">
                <img alt="applications" src="_images/web-design-32.png">
                <h1>Application UI</h1>
                <div>Creating and customizing a user interface for your apps</div>
            </a>
            <a class="box_home_page" href="C_Deployment/index.html">
                <img alt="deployment" src="_images/network-care-32.png">
                <h1>Deployment</h1>
                <div>Distributing your apps with AIMMS PRO (on-premise or cloud-hosted)</div>
            </a>
            <a class="box_home_page" href="C_Evolution/index.html">
                <img alt="evolution" src="_images/time-machine-32.png">
                <h1>Software Evolution</h1>
                <div>Implementing new AIMMS features, planning for deprecation</div>
            </a>
            <a class="box_home_page" href="https://scnavigator-manual.aimms.com/">
                <img alt="navigator" src="_images/global-chain-32.png">
                <h1>SC Navigator</h1>
                <div>Help and documentation for the SC Navigator suite of apps</div>
            </a>
        </div>
    </div>
    
-----------------------------------------------------------

.. toctree::
   :maxdepth: 1
   :titlesonly:
   :hidden:

   C_Getting_Started/index
   C_Developer/index
   C_UI/index
   C_Deployment/index
   C_Evolution/index
   Recently_added
   

Use, contribute, fix, improve the theme

Run the theme locally

If you would like to modify the theme, or correct something, you may build the theme locally.

To do so, please download the theme repo on your computer, and run in the repo location:

python setup.py develop

First, you may want to uninstall the theme installed, by running python -m pip uninstall sphinx-aimms-theme

Contribution and support

If you would like to propose a change, or if something's not clear, just send an e-mail to support@aimms.com

Note

All readthedocs options are available as well !

https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html

This theme is highly customizable on both the page level and on a global level. See https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html