@@ -73,7 +73,7 @@ White space:
7373 keyword and the opening parenthesis.
7474- Put 1 space after a comma, and 1 space around operators.
7575
76- Braces:
76+ Braces:
7777- Use braces for all blocks, even no-line and single-line pieces of
7878 code.
7979- Put opening braces on the end of the line it belongs to, not on
@@ -135,3 +135,76 @@ Type declarations:
135135 int member;
136136 void *data;
137137 } my_struct_t;
138+
139+ Documentation conventions
140+ =========================
141+
142+ MicroPython generally follows CPython in documentation process and
143+ conventions. reStructuredText syntax is used for the documention.
144+
145+ Specific conventions/suggestions:
146+
147+ * Use ` * ` markup to refer to arguments of a function, e.g.:
148+
149+ ```
150+ .. method:: poll.unregister(obj)
151+
152+ Unregister *obj* from polling.
153+ ```
154+
155+ * Use following syntax for cross-references/cross-links:
156+
157+ ```
158+ :func:`foo` - function foo in current module
159+ :func:`module1.foo` - function foo in module "module1"
160+ (similarly for other referent types)
161+ :class:`Foo` - class Foo
162+ :meth:`Class.method1` - method1 in Class
163+ :meth:`~Class.method1` - method1 in Class, but rendered just as "method1()",
164+ not "Class.method1()"
165+ :meth:`title <method1>` - reference method1, but render as "title" (use only
166+ if really needed)
167+ :mod:`module1` - module module1
168+
169+ `symbol` - generic xref syntax which can replace any of the above in case
170+ the xref is unambiguous. If there's ambiguity, there will be a warning
171+ during docs generation, which need to be fixed using one of the syntaxes
172+ above
173+ ```
174+
175+ * Cross-referencing arbitrary locations
176+ ~~~
177+ .. _xref_target:
178+
179+ Normal non-indented text.
180+
181+ This is :ref:`reference <xref_target>`.
182+
183+ (If xref target is followed by section title, can be just
184+ :ref:`xref_target`).
185+ ~~~
186+
187+ * Linking to external URL:
188+ ```
189+ `link text <http://foo.com/...>`_
190+ ```
191+
192+ * Referencing builtin singleton objects:
193+ ```
194+ ``None``, ``True``, ``False``
195+ ```
196+
197+ * Use following syntax to create common description for more than one element:
198+ ~~~
199+ .. function:: foo(x)
200+ bar(y)
201+
202+ Description common to foo() and bar().
203+ ~~~
204+
205+
206+ More detailed guides and quickrefs:
207+
208+ * http://www.sphinx-doc.org/en/stable/rest.html
209+ * http://www.sphinx-doc.org/en/stable/markup/inline.html
210+ * http://docutils.sourceforge.net/docs/user/rst/quickref.html
0 commit comments