From e92602ba27915041ecb321b770bec9a37610201c Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sun, 25 Jun 2017 00:13:13 +0300
Subject: [PATCH] CODECONVENTIONS: Start to describe docs conventions.

---
 CODECONVENTIONS.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/CODECONVENTIONS.md b/CODECONVENTIONS.md
index cf5a468d36..860f1f88ec 100644
--- a/CODECONVENTIONS.md
+++ b/CODECONVENTIONS.md
@@ -135,3 +135,70 @@ Type declarations:
         int member;
         void *data;
     } my_struct_t;
+
+Documentation conventions
+=========================
+
+MicroPython generally follows CPython in documentation process and
+conventions. reStructuredText syntax is used for the documention.
+
+Specific conventions/suggestions:
+
+* Use `*` markup to refer to arguments of a function, e.g.:
+
+```
+.. method:: poll.unregister(obj)
+
+   Unregister *obj* from polling.
+```
+
+* Use following syntax for cross-references/cross-links:
+
+```
+:func:`foo` - function foo in current module
+:func:`module1.foo` - function foo in module "module1"
+    (similarly for other referent types)
+:class:`Foo` - class Foo
+:meth:`Class.method1` - method1 in Class
+:meth:`~Class.method1` - method1 in Class, but rendered just as "method1()",
+    not "Class.method1()"
+:meth:`title <method1>` - reference method1, but render as "title" (use only
+    if really needed)
+:mod:`module1` - module module1
+
+`symbol` - generic xref syntax which can replace any of the above in case
+    the xref is unambiguous. If there's ambiguity, there will be a warning
+    during docs generation, which need to be fixed using one of the syntaxes
+    above
+```
+
+* Cross-referencing arbitrary locations
+~~~
+.. _xref_target:
+
+Normal non-indented text.
+
+This is :ref:`reference <xref_target>`.
+
+(If xref target is followed by section title, can be just
+:ref:`xref_target`).
+~~~
+
+* Use following syntax to create common description for more than one element:
+~~~
+.. function:: foo(x)
+              bar(y)
+
+   Description common to foo() and bar().
+~~~
+
+* Linking to external URL:
+```
+`link text <http://foo.com/...>`_
+```
+
+More detailed guides and quickrefs:
+
+* http://www.sphinx-doc.org/en/stable/rest.html
+* http://www.sphinx-doc.org/en/stable/markup/inline.html
+* http://docutils.sourceforge.net/docs/user/rst/quickref.html