AIMMS Domain.md 5.08 KB
Newer Older
1 2 3 4 5
AIMMS Domain for Sphinx
=========================

As first introduction to domains, please refer to [Sphinx Domain Docs](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) to document your own AIMMS code.

ArthurH's avatar
ArthurH committed
6
This AIMMS Domain is build up from the [Javascript Domain](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-javascript-domain)
7 8 9 10 11

Basic Usage
============

```
ArthurH's avatar
ArthurH committed
12
.. aimms:parameter:: P_demand(l)
13

ArthurH's avatar
ArthurH committed
14
   Numerical demand of a certain location l.
15 16
```

ArthurH's avatar
ArthurH committed
17
This describes an AIMMS parameter called P_demand indexed over the l index.
18 19 20

The domains also provide roles that link back to these object descriptions. For example, to link to the parameter described in the example above, you could say

ArthurH's avatar
ArthurH committed
21
```
ArthurH's avatar
ArthurH committed
22
The parameter :aimms:parameter:`P_demand` gives similar data.
ArthurH's avatar
ArthurH committed
23
```
24 25 26

As you can see, both directive and role names contain the domain name and the directive name. 

ArthurH's avatar
ArthurH committed
27 28
Example
=========
29

ArthurH's avatar
ArthurH committed
30
The AIMMS Domain is used extensively in the [AIMMS Function Reference](https://documentation.aimms.com/functionreference/index.html).
31 32 33 34

The AIMMS Domain
===================

ArthurH's avatar
ArthurH committed
35
The AIMMS domain (name ``aimms``) provides the following directives:
36

ArthurH's avatar
ArthurH committed
37
```
38
.. aimms:module:: name
ArthurH's avatar
ArthurH committed
39 40
```

41 42 43 44
This directive sets the module name for object declarations that follow after. The module name is used in the global module index and in cross references. This directive does not create an object heading like py:class would, for example.

By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the noindex option is specified. If this option is specified, the directive will only update the current module name.

ArthurH's avatar
ArthurH committed
45
```
46
.. aimms:function:: name(signature)
ArthurH's avatar
ArthurH committed
47 48
```

49 50 51 52
Describes an AIMMS function. If you want to describe arguments as optional use square brackets as documented for Python signatures.

You can use fields to give more details about arguments and their expected types, errors which may be thrown by the function, and the value being returned:

ArthurH's avatar
ArthurH committed
53
```
54 55 56 57 58 59 60 61 62
.. aimms:function:: MyFunction(href, callback[, errback])

   :attribute string href: An URI to the location of the resource.
   :attribute callback: Gets called with the object.
   :attribute errback:
       Gets called in case the request fails. And a lot of other
       text so we need multiple lines.
   :throws SomeError: For whatever reason in that case.
   :returns: Something.
ArthurH's avatar
ArthurH committed
63
```
64 65 66

List of supported types, following the same rules as ``aimms:function::`` :

ArthurH's avatar
ArthurH committed
67

ArthurH's avatar
ArthurH committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81
| Supported Types             |
|-----------------------------|
| aimms:function::            |
| aimms:procedure::           |
| aimms:externalprocedure::   |
| aimms:parameter::           |
| aimms:elementparameter::    |
| aimms:stringparameter::     |
| aimms:set::                 |
| aimms:variable::            |
| aimms:constraint::          |
| aimms:mathematicalprogram:: |
| aimms:file::                |
| aimms:handle::              |
ArthurH's avatar
ArthurH committed
82

83 84 85

List of supported types, following the same rules as ``aimms:module::`` :

ArthurH's avatar
ArthurH committed
86 87 88 89 90
| Supported Types             |
|-----------------------------|
| aimms:module::              |
| aimms:librarymodule::       |

ArthurH's avatar
ArthurH committed
91

92 93 94

These roles are provided to refer to the described objects:

ArthurH's avatar
ArthurH committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
| Supported roles             |
|-----------------------------|
| :aimms:func:                |
| :aimms:procedure:           |
| :aimms:librarymodule:       |
| :aimms:externalprocedure:   |
| :aimms:parameter:           |
| :aimms:elementparameter:    |
| :aimms:stringparameter:     |
| :aimms:set:                 |
| :aimms:variable:            |
| :aimms:constraint:          |
| :aimms:mathematicalprogram: |
| :aimms:file:                |
| :aimms:handle:              |
ArthurH's avatar
ArthurH committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

Coupling the domain with intersphinx
=======================================

Cross link with other AIMMS documentation websites

[Intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) extension enables you to import the global index (a list of all titles, files and declared domain objects with their URL) from another sphinx repository (website).

Basic usage
-

For example, you may refer to ``AllIdentifiers`` set from the AIMMS function reference using the following syntax:

```
:aimms:set:`AllIdentifiers`
```

This will result in an clickable hyperlink redirecting you to:

https://documentation.aimms.com/functionreference/predefined-identifiers/model-related-identifiers/allidentifiers.html


**Tip:** if you are not sure about the type (set, parameter, elementparameter, etc.), you may also use 
```
:any:`AllIdentifiers`
``` 

This will be available provided that you've included the AIMMS function reference in your intersphinx set up. You can do so by adding to the following line to the ``conf.py`` file:

``` python
intersphinx_mapping = {'functionreference': ('https://documentation.aimms.com/functionreference/',
                                  (None,'objects-functionreference.inv'))}
```

``objects-functionreference.inv`` is a potential backup that you may include in your repository if you can't connect to the internet while building your docs as described [here](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping)