@@ -26,6 +26,27 @@ require such detailed description.
2626To get good practical examples of good commits and their messages, browse
2727the ` git log ` of the project.
2828
29+ MicroPython doesn't require explicit sign-off for patches ("Signed-off-by"
30+ lines and similar). Instead, the commit message, and your name and email
31+ address on it construes your sign-off of the following:
32+
33+ * That you wrote the change yourself, or took it from a project with
34+ a compatible license (in the latter case the commit message, and possibly
35+ source code should provide reference where the implementation was taken
36+ from and give credit to the original author, as required by the license).
37+ * That you are allowed to release these changes to an open-source project
38+ (for example, changes done during paid work for a third party may require
39+ explicit approval from that third party).
40+ * That you (or your employer) agree to release the changes under
41+ MicroPython's license, which is the MIT license. Note that you retain
42+ copyright for your changes (for smaller changes, the commit message
43+ conveys your copyright; if you make significant changes to a particular
44+ source module, you're welcome to add your name to the file header).
45+ * Your signature for all of the above, which is the 'Author' line in
46+ the commit message, and which should include your full real name and
47+ a valid and active email address by which you can be contacted in the
48+ foreseeable future.
49+
2950Python code conventions
3051=======================
3152
@@ -52,7 +73,7 @@ White space:
5273 keyword and the opening parenthesis.
5374- Put 1 space after a comma, and 1 space around operators.
5475
55- Braces:
76+ Braces:
5677- Use braces for all blocks, even no-line and single-line pieces of
5778 code.
5879- Put opening braces on the end of the line it belongs to, not on
@@ -114,3 +135,76 @@ Type declarations:
114135 int member;
115136 void *data;
116137 } 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