Documentation guidelines

This PR rephrases the guidelines written by @rocky in Mathics3/pymathics-natlang#12.

docs/extending/developing-code/extending/documentation-markup.rst

@@ -144,3 +144,86 @@ moving something like this to a pytest unit test which is far more flexibile.
 +------------------------+-----------------------------------------------------------+
 
 *Todo: give examples of each of these.*
+
+
+
+Guidelines for writting documentation
+=====================================
+
+
+When a new builtin is added, it is expected to follow the following guidelines regarding the format of the docstrings and `summary_text` attribute, which are used for building the documentation. Some of these guidelines are reinforced by the CI.
+
+`summary_text` is used in the online documentation as a brief description of what the symbol represents. For builtins representing the head of expressions, `summary_text`, starts with an active verb with the word in lowercase, e.g. "retrieve" as opposed to "Retrieve".  If you look at the section that the summary appears it is nice to use the same verb for similar kinds of things. For example we may "list" builtins that end with "List" (EdgeList, VertexList" but, "find" builtins with "Index" at the end of the name "EdgeIndex", "VertexIndex". For variables, and options, we _do not_ start with an active verb.
+
+Docstrings contain information about the content of the documentation entry. They must consist on the following parts:
+* Title and url refs.
+* `<dl>..</dl>` usage description.
+* Extended description section.
+
+
+
+
+Title
+------
+
+We can use use pymathics.graph as an example to compare against.
+
+If there is a wikipedia entry that goes first. See AdjacencyList for an example.
+
+It may be that only a part of the Wikipedia entry is available. Fill in other text outside of the URL. See DirectedEdge for an example. 
+
+If there is no wikipedia mention, it is okay to give some free title. EdgeDelete is an example. 
+
+Or you can omit the title altogether. `RandomGraph` is an Example.
+
+In general we go with the Wikipedia name rather than the WMA for the title. And this includes symbolic parameter names. CompleteKaryTree is an example.
+
+When the only thing we have is a WMA link we add "link" to the title. EdgeList is an example .
+
+Remember that line breaks are significant. `\` can be used to wrap a long line. 
+Start the url name on a new line after `<url>`. For example: 
+
+```
+<url>
+:WMA link:
+https://reference.wolfram.com/language/ref/EdgeList.html</url>
+```
+
+Note that there is no line break at the end before or after `</url>`. 
+
+Please don't get too creative in formatting. There are many other areas in the selection of words to describe what is need may require care. But here it shouldn't require much thought for the _formatting_ aspects. 
+
+If the URL is too long, of course, you can split it up in a way that the URL tag understands.  Please inspect the URLs in a browser for change.  Ideally you would click the link, but if not or before, look at the URL that appears when the link is hovered over. 
+
+
+
+There should be at least one doc example for each function in that is focused on describing what the function does (not how it can be tested).  Examples for tests should be added as pytests.
+
+
+`<dl>...</dl>` usage block
+----------------------------
+
+The title must be followed by a `<dl>...</dl>`, describing the diffferent ways to use the symbol. For example, in the  `Builtin` class `LaguerreL`:
+
+    ```
+     <dl>
+       <dt>'LaguerreL[$n$, $x$]'
+       <dd>returns the Laguerre polynomial L_$n$($x$).
+
+       <dt>'LaguerreL[$n$, $a$, $x$]'
+       <dd>returns the generalised Laguerre polynomial L^$a$_$n$($x$).
+     </dl>
+    ```
+
+Notice the 2 space indentation regarding `<dl>` tag.
+
+Extended description section
+-----------------------------
+
+After the usage block, it is expected a brief explanation about the context in which the symbol is used, including examples of use, details of the implementations and possible issues. This section must contain at least one doctest example for each entry in the usage block.
+
+
+
+
+
+