{"id":37558307,"url":"https://github.com/aimms/language-reference","last_synced_at":"2026-01-16T09:03:23.347Z","repository":{"id":53621097,"uuid":"345681392","full_name":"aimms/language-reference","owner":"aimms","description":"The AIMMS Language Reference published at https://documentation.aimms.com/language-reference/index.html","archived":false,"fork":false,"pushed_at":"2025-09-11T12:31:55.000Z","size":1170,"stargazers_count":2,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-11T15:45:36.194Z","etag":null,"topics":["aimms","documentation","python","sphinx"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aimms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-03-08T14:20:25.000Z","updated_at":"2025-09-11T12:31:59.000Z","dependencies_parsed_at":"2023-12-15T10:46:57.575Z","dependency_job_id":"f74cbc01-4d88-4e59-8b17-2e7b7e8ba7b4","html_url":"https://github.com/aimms/language-reference","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aimms/language-reference","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimms%2Flanguage-reference","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimms%2Flanguage-reference/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimms%2Flanguage-reference/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimms%2Flanguage-reference/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aimms","download_url":"https://codeload.github.com/aimms/language-reference/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimms%2Flanguage-reference/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aimms","documentation","python","sphinx"],"created_at":"2026-01-16T09:03:23.235Z","updated_at":"2026-01-16T09:03:23.334Z","avatar_url":"https://github.com/aimms.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[[_TOC_]]\n\nBuild Locally the HTML documentation\n--------------------------------------\n\n**Requirements:**\n - [Python 3.X](https://www.python.org/downloads/)\n - [Sphinx package](http://www.sphinx-doc.org/en/master/) (run `python3 -m pip install sphinx`)\n - [Sphinx AIMMS theme](https://gitlab.com/ArthurdHerbemont/sphinx-aimms-theme) (run `python3 -m pip install sphinx-aimms-theme`)\n - [AIMMS code blocks for PDF](https://gitlab.com/ArthurdHerbemont/aimms-pygments-style) (run `python3 -m pip install aimms-pygments-style`) \n - [BibTeX] (run `python3 -m pip install sphinxcontrib.bibtex`)\n\nAfter installing all the above requirements, please go to the location of your previously cloned documentation folder:\n * Open a console prompt from this location, using ``ATL+D`` and typing ``cmd`` in the URL of your file explorer (awesome)\n * run ``make html`` (the first time, this may take some time, like 20 secs. progress is shown in your console)\n \u003e 💡 You may also run `python3 -msphinx . _build/html` (to be sure to use a specific python version). [More docs](https://www.sphinx-doc.org/en/master/man/sphinx-build.html)\n\n**Alternative**\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cb\u003eClick me to show an example 👇\u003c/b\u003e\n\u003c/summary\u003e\n![image](/uploads/af294070a540237ba141ac325763febd/image.png) \n\n\n\n* As you may see at the bottom of the wonderfully colored prompt, **your html pages are in `_build\\html` folder**, located in the current working directory (the same as always). You may check the build by opening any of those.\n* The red text are warnings (any error would actually break the building process, as in AIMMS): **Those warnings should be avoided**. Most of the time, this is due to a misuse of sphinx. You may correct them yourself, because your are awesome. Or let them be because your don't understand them. In any case, through your development please mind that **you should avoid to create any new warnings** (ask around if you don't understand)\n* Be aware to make title underline longer than the title itself (warning would look like the above cmd prompt image)\n* ⚠️ file names are case sensitive on linux, and not on windows. Thus, your build may break on gitlab, and not locally on your computer. \n\n\u003c/details\u003e\n\n\n**Alternative**\n\nAs an alternative to setting things up on your local computer, use a docker container, see https://aimmsopt.sharepoint.com/sites/InternalSupportDocumentation/SitePages/Using-docker-to-build-the-documentation-locally.aspx\n\n\n\u003e **💡1:** GitLab CI is following exactly the same process when building the documentation in the pipeline. This is defined in the [.gitlab-ci.yml](.gitlab-ci.yml) file. More details below\n\n\u003e **⚠️2:** When pushing to the **master branch only**, the repo is built and **pushed (merged) to [documentation.aimms.com/language-reference/](https://documentation.aimms.com/language-reference/index.html)**.\n\n\u003e **⚠️3:** If any warning is raised on gitlab, **the pipeline fails**\n\n\nThe Pipeline\n-\n\nEvery push to gitlab remote will run a pipeline. This pipeline first \"Test\" stage contains 3 different jobs as defined in [.gitlab-ci.yml](.gitlab-ci.yml)\n\n![image](https://gitlab.aimms.com/aimms/documentation/-/wikis/uploads/cc98f149f3858630e6a760a35c9e0c98/image.png)\n\n| job name | description | condition |\n| ------ | ------ | ----- |\n| ``build`` | builds the docs using the latest sphinx version | ❌ If any warning is raised, the job and pipeline fails |\n| ``linkcheck`` | checks every external link **and** anchor | ❌ If any link **or** anchor is broken, the job and pipeline fails |\n| ``spellcheck`` | checks the spelling of every word | ⚠️ If any spelling is broken, the job fails, but this job is **allowed to fail** |\n\n\u003cdetails\u003e\n\u003csummary\u003e\n \u003cb\u003eIf \u003ccode\u003ebuild\u003c/code\u003e fails on gitlab, but not locally, what should I do ? 👇\u003c/b\u003e\n\u003c/summary\u003e\n\n1. look at the error/warning in the pipeline\n1. Upgrade your sphinx version and sphinx-aimms-theme version (`python -mpip --upgrade sphinx`)\n1. Linux filenames are case sensitive. Double check\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cb\u003eIf \u003ccode\u003elinkcheck\u003c/code\u003e fails on gitlab, but not locally, what should I do ? 👇\u003c/b\u003e\n\u003c/summary\u003e\n\n1. if `build` also fails, go to fix ``build`` first\n1. look at the error/warning in the pipeline\n   1. fix your broken link\n   1. fix expired link, cause website no more reachable - Thanks for your help !\n1. Fix links locally using `make linkcheck` or `python -msphinx -b linkcheck . _build/html`\n1. upgrade your sphinx version and sphinx-aimms-theme version (`python -mpip --upgrade sphinx sphinx-aimms-theme`)\n1. re-run the job in gitlab: **some links might be temporarily not reachable**\n1. If there is a link you want to **ignore**, put it \n``` \n``example.com`` \n```\n\u003c/details\u003e\n\n**If ``spellcheck`` fails, what should I do ?**\n\n- Don't bother ☺️\n\n**When pushing to the master branch**\n\nA push to master will run the pipeline and, if the `Test` stage is successful, it will copy the docs to [documentation.aimms.com/language-reference/index.html](https://documentation.aimms.com/language-reference/index.html)\n\nIf the pipeline fails, no copy will happen, thus website stays unchanged\n\n**Notes**\n1. If there is a link you want to **ignore**, put it \n``` \n``example.com`` \n```\n\n\nStyle guide\n==============\n\n**Guidelines**\n\n1. PUBLISHING PROCESS - Create a Create a new branch for editing, and merge to develop branch when ready. It will be reviewed and published weekly. Please don't work in the master branch except in urgent cases (use your judgment).\n\n2. IMAGES - When using screenshots, leave plenty of space around the area you want to show so the image can be edited and edges can be beautified. Use markup sparingly.\n\n3. IMAGE LOCATION - Keep icons in the icon folder (they can be reused for many docs). Specific images should be in their own ``images`` folder next to the RST file. \n\n4. FILE NAME CONVENTIONS - Use the Gitlab ticket number for the \"id number\" of your article and give it a short but descriptive file name. (Occasionally there can be more than one article under the same ticket number, but generally try to make a new ticket for each article.)\n\n5. RST CONVENTIONS - Always follow the same code conventions for headings, images, etc. The code is flexible, but we want docs to be consistent.\n\n6. LINKING TO ARBITRARY ANCHORS - Titles may change, headings may change. Avoid link to headings by their title, instead create references (anchors) in the code using :ref: - if the title of a heading changes, links in other docs won't be broken.\n\n7. LINKING TO OTHER FILES - Use :doc: to link to other files in the same repo. It will automatically pull the up-to-date title.\n\n8. LINKING TO FUNCTION REFERENCE - Use `:aimms:set:\\`AllIdentifiers\\`` or `:any:\\`AllIdentifiers\\``. This will create a link to the documentation for that function.\n\n\n\n**Quick reference**\n\n`== Title (level 1) marker`\n\n`-- Heading (level 2) marker`\n\n`^^ Subheading (level 3) marker`\n\n`.. Commented text`\n\n`.. code-block:: aimms`\n\n`*Italics*`\n\n`**Bold**`\n\n` ``Monospace font`` `\n\n`#. Numbered list item`\n\n`* Unordered list item`\n\n`` `External Link \u003cwww.url.com\u003e`_``\n\nSee also: \nhttp://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\n\n**Useful directives and roles in reST**\n\n*Table of contents or index*\n\n`.. toctree::`\n\nUse the sub-options :max-depth: or :titlesonly: appropriately, otherwise all sub-headings will show up in the table of contents leading to a long long list. Below two are equivalent.\n\n```\n.. toctree::\n   :maxdepth: 1\n```\n\n```\n.. toctree::\n   :titlesonly:\n```\n\n*Image*\n\n.. image:: /relativeFilePath/image.png\n\nhttp://docutils.sourceforge.net/docs/ref/rst/directives.html#image \n\n*Code blocks, numbered*\n\n     .. code-block::\n        :linenos:\n\n*Substitution*\n\nCan be useful for images, but any object or text string you may want to single-source for use in multiple docs. \n\nName the substitution in the header\n\n\t.. |image-name| image:: /Images/image-name.png\n\nCall the substitution in the document\n\n\t|image-name|\n\nhttp://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions\n\n\n*Download*\n\nAdd a downloadable file to your page\n\n\t:download:`this example script \u003cdownloads/example.py\u003e`.\n\n*Relative file path*\n\nThe given filename is usually relative to the current file. (../ represents go up \na level, ../../ represents go up two levels, etc.)\n\nhttp://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#referencing-downloadable-files\n\n\n*Relative link*\n\nTo link to another reST file in the same repo, you can use the :doc: role\n\n\t:doc:`file-name`\nor\n\n\t:doc:`../file-name`\n\n\nThe link displays the title within the given document, or specify text to display explicitly\n\n        :doc:`explicit title \u003cfilePath/file-name\u003e`\n\nhttp://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents\n\n\n*Cross-reference*\n\nLike an anchor, but can be referenced by name from any other doc in the repo by name (no file path needed). Used above a section header.\n\nName the anchor\n\n\t.. _my-reference-label:\n\n\tSection to cross-reference\n\t--------------------------\n\n\tThis is the text of the section.\n\nRefer to the anchor\n\n\tSee :ref:`my-reference-label`.\n\nhttp://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref\n\n\n*Include*\n\nUse this to add contents of an entire file in the repo to your document as a snippet. (We use this in How-to for the feedback form at the bottom.)\n\n\t.. include:: inclusion.txt\n\nhttp://docutils.sourceforge.net/docs/ref/rst/directives.html#include\n\n\nPrereq's to build a PDF version (optional) \n-------------------------------------------\n\nYou can use the ``make latexpdf`` command to locally create a .pdf from the .rst source files.\n\nFirst, make sure you installed Latex - https://miktex.org/howto/install-miktex\n\nThen, to get the AIMMS code to look right, you need to run this:\n   \n   ``python -m pip install aimms-pygments-style``\n \n   This will install an extension enabling latex to find the AIMMS style sheet define in the following open source repo \n   https://gitlab.com/ArthurdHerbemont/aimms-pygments-style. Please contribute if you think you can improve it ! :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimms%2Flanguage-reference","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faimms%2Flanguage-reference","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimms%2Flanguage-reference/lists"}