-
Notifications
You must be signed in to change notification settings - Fork 4
MatrixDocstrings
This document describes the addition of docstrings to the matrix customization system code, including how to add docstrings to typedefs and how to add links to new documentation for use in these docstrings.
A docstring can be added to a typedef when a typedef is added or updated from the python files in gmcs/linglib using parameters in mylang.add(). There are two types of docstrings available to add to a typedef: links to documentation pages and general docstrings. The first type (links to documentation) is a pre-formatted docstring that can include a list of matrix documentation library links relevant to the typedef. The second type (general docstring) can be used to include your own text with no preformatting. The two styles can be added to the same typedef.
The first type (links to documentation) will appear like this on general typedefs in the your_language_name.tdl file:
png :+ [ PER person,
NUM number ]
"""
This type as generated from the customization system bore constraints from these libraries:
https://github.com/delph-in/docs/wiki/MatrixDoc_Number
https://github.com/delph-in/docs/wiki/MatrixDoc_Person
""".
The second type (general docstring) will appear like this on general typedefs in the your_language_name.tdl file:
png :+ [ PER person,
NUM number ]
"""
This is a sample sentence describing this type.
""".
When using LTDB, the docstrings you've added to your grammar will automatically appear on the description page for each type in your grammar.
[This page is still under construction]
To add a docstring with links to specific doc pages relevant to the typedef, simply add the line "links = set_links([X1, X2, X3, ...])" as a parameter to your call to mylang.add(), where the Xs in the list are each the name of a docpage_LINK global variable (as found in docstrings.py) that you want listed in the docstring. Make sure that the docpage_LINK(s) you want to use and the method set_links are imported from docstrings.py within the file you are working on.
[This page is still under construction]
set_links is a function in the file docstrings.py which takes a list docpage_LINK(s) and creates the full version of each link by concatenating the general MATRIX_DOC_LINK to the beginning of each of them. Then, it creates a set() from this list (so there are no repeats) and returns it.
To add a general docstring to your typedef, simply add the following line as a parameter to your call to mylang.add(): docstring = "your_text_here". The String "your_text_here" contains the text you want in the docstring.
[This page is still under construction]
You can add both documentation links and a general docstring to the same typedef. When both are added, the general text appears under the links within the same docstring.
[This page is still under construction]
In gmcs/linglib, there is a python file called docstrings.py. This is the core file for storing the links to documentation pages (that can be added to docstrings) and the main python method for adding/formatting doc links in a typedef.
At the top of the file, there is a global variable called MATRIX_DOC_LINK. This is the main link to the matrix doc pages, from which all other pages can be linked. Currently, the variable is set to "https://github.com/delph-in/docs/wiki/", but this can be changed if the docs ever move location.
After the general MATRIX_DOC_LINK, you can find a global variable for every Matrix Doc page/library. These variables are strings which contain the name of each doc page/library, which will take you to the specific doc pages when they are added to the end of the general MATRIX_DOC_LINK. For example, the variable CASE_LINK is defined as "MatrixDoc_Case", so when this variable is added to the end of MATRIX_DOC_LINK, you get "https://github.com/delph-in/docs/wiki/MatrixDoc_Case", which is the fulll link to the matrix doc page on Case.
To add a new link to a new library, simply define a global variable as yourlibraryname_LINK = "MatrixDoc_nameofyourlibrary". You can make sure that you've added the correct info by simply checking that "https://github.com/delph-in/docs/wiki/MatrixDoc_nameofyourlibrary" (MATRIX_DOC_LINK + yourlibraryname_LINK) links to the correct doc page.
[This page is still under construction]
Home | Forum | Discussions | Events