changeset 671443acd8a0 in www.tryton.org:default
details: https://hg.tryton.org/www.tryton.org?cmd=changeset;node=671443acd8a0
description:
Add documentation style guide
issue9636
review300511003
diffstat:
app.py | 28 +++
static/images/banner-document-400.jpg | Bin
static/images/banner-document-800.jpg | Bin
static/images/banner-document.jpg | Bin
templates/develop.html | 58 ++-----
templates/guidelines/code.html | 74 +++++++++
templates/guidelines/documentation.html | 238 ++++++++++++++++++++++++++++++++
templates/guidelines/help.html | 130 +++++++++++++++++
templates/guidelines/howto.html | 90 ++++++++++++
9 files changed, 576 insertions(+), 42 deletions(-)
diffs (677 lines):
diff -r 66a9b14309ac -r 671443acd8a0 app.py
--- a/app.py Tue Dec 22 22:42:38 2020 +0100
+++ b/app.py Wed Dec 30 16:04:36 2020 +0000
@@ -635,6 +635,34 @@
return render_template('develop.html')
+@app.route('/develop/guidelines/code')
+@cache.cached(key_prefix=cache_key_prefix_view)
+@add_links(PRECONNECT_HEADERS + JS_LINK_HEADERS + CSS_LINK_HEADERS)
+def guidelines_code():
+ return render_template('guidelines/code.html')
+
+
+@app.route('/develop/guidelines/documentation')
+@cache.cached(key_prefix=cache_key_prefix_view)
+@add_links(PRECONNECT_HEADERS + JS_LINK_HEADERS + CSS_LINK_HEADERS)
+def guidelines_documentation():
+ return render_template('guidelines/documentation.html')
+
+
+@app.route('/develop/guidelines/help-text')
+@cache.cached(key_prefix=cache_key_prefix_view)
+@add_links(PRECONNECT_HEADERS + JS_LINK_HEADERS + CSS_LINK_HEADERS)
+def guidelines_documentation_help():
+ return render_template('guidelines/help.html')
+
+
+@app.route('/develop/guidelines/howto')
+@cache.cached(key_prefix=cache_key_prefix_view)
+@add_links(PRECONNECT_HEADERS + JS_LINK_HEADERS + CSS_LINK_HEADERS)
+def guidelines_documentation_howto():
+ return render_template('guidelines/howto.html')
+
+
@app.route('/foundation')
@cache.cached(key_prefix=cache_key_prefix_view)
@add_links(PRECONNECT_HEADERS + JS_LINK_HEADERS + CSS_LINK_HEADERS)
diff -r 66a9b14309ac -r 671443acd8a0 static/images/banner-document-400.jpg
Binary file static/images/banner-document-400.jpg has changed
diff -r 66a9b14309ac -r 671443acd8a0 static/images/banner-document-800.jpg
Binary file static/images/banner-document-800.jpg has changed
diff -r 66a9b14309ac -r 671443acd8a0 static/images/banner-document.jpg
Binary file static/images/banner-document.jpg has changed
diff -r 66a9b14309ac -r 671443acd8a0 templates/develop.html
--- a/templates/develop.html Tue Dec 22 22:42:38 2020 +0100
+++ b/templates/develop.html Wed Dec 30 16:04:36 2020 +0000
@@ -4,9 +4,9 @@
{% set toc = [
("Report an Issue", 'report-issue', None),
("Submit a Change", 'submit-change', None),
- ("Coding Guidelines", 'coding-guidelines', [
- ("Code Style", 'code-style', None),
- ("Best Practices", 'best-practices', None),
+ ("Guidelines", 'guidelines', [
+ ("Code", 'guidelines-code', None),
+ ("Documentation", 'guidelines-documentation', None),
]),
("Requirements", 'requirements', None),
("Rules", 'rules', None),
@@ -61,7 +61,7 @@
<div class="subsection">
<h2 id="submit-change">Submit a Change</h2>
<ul>
- <li>Follow the <a href="#coding-guidelines">coding guidelines</a>.</li>
+ <li>Follow the <a href="#guidelines">guidelines</a>.</li>
<li>Submit your change to our <a
href="https://codereview.tryton.org/";>review tool</a> using the <a
href="https://codereview.tryton.org/static/upload.py";>upload.py</a> script (see
the <a href="https://github.com/rietveld-codereview/rietveld/wiki";>help
page</a>).</li>
<li>Make sure the review has the repository name at the start of the
review title,
and ensure the review description contains a reference to the
issue (e.g.: <span class="text-monospace">issue1234</span>).</li>
@@ -78,47 +78,21 @@
</div>
</div>
<div class="subsection">
- <h2 id="coding-guidelines">Coding Guidelines</h2>
- <p>The Tryton Project strongly recommends the following guidelines.</p>
- <h3 id="code-style">Code Style</h3>
- <h4>Python</h4>
- <p>Code style, in general, follows <a
href="https://www.python.org/dev/peps/pep-0008/";>PEP 8</a>:</p>
- <ul>
- <li>Use 4 spaces for indentation.</li>
- <li>Avoid the usage of <span class="text-monospace">from M import
*</span>.</li>
- <li>If unsure about conformity use <a
href="https://pypi.org/project/flake8/";>flake8</a> to check the code (with
option <span
class="text-monospace">ignore=E123,E124,E126,E128,E741,W503</span>).</li>
- <li>Breaking lines:
- <ul>
- <li>Use 4 spaces per bracket pair.</li>
- <li>Prefer parenthesis over backslash.</li>
- </ul>
- </li>
- </ul>
- <h4>XML</h4>
+ <h2 id="guidelines">Guidelines</h2>
+ <p>The Tryton Project has guidelines for both code and documentation.</p>
+ <h3 id="guidelines-code">Code</h3>
<ul>
- <li>Use 4 spaces for indentation.</li>
- <li>No 80 columns limitation.</li>
- <li>Opening tag on single line or one attribute per line.</li>
+ <li>The <a href="{{ url_for('guidelines_code') }}">Coding
Guidelines</a> should be followed for any review you submit.</li>
</ul>
- <h3 id="best-practices">Best Practices</h3>
- <ul>
- <li>Use doc-strings and comments in your code.</li>
- <li>Never pass keyword arguments as positional arguments when calling
a method.</li>
- <li>In the very beginning (right under the doc-string) of a method
definition, define all pool objects that will be used (<span
class="text-monospace">pool.get(...)</span>).</li>
- </ul>
- <h4>Naming of modules, classes, variables</h4>
+ <h3 id="guidelines-documentation">Documentation</h3>
+ <p>
+ There are several different places that Tryton documentation can be found.
+ This is to make sure it is available in the right format, at the right
time, for different use cases.</p>
+ <p>So to avoid duplication, and keep the documentation organised and
maintainable there are several sets of guidelines:</p>
<ul>
- <li>A name should be as descriptive and as short as possible.</li>
- <li>Avoid unnecessary duplication of names.</li>
- <li>Naming structure of a model or module must follow these rules:
- <ul>
- <li>First part of the name is the general function of the
module or model,</li>
- <li>after this come the less general parts of the name (i.e.
the more specific name parts) for the module or model</li>
- <li>If you are unsure with naming, please ask first on the <a
href="{{ url_for('forum', _anchor='irc') }}">#tryton channel</a></li>
- </ul>
- </li>
- <li>For modules and method names use an underscore to separate the
parts of name.</li>
- <li>For naming classes use <a
href="https://en.wikipedia.org/wiki/CamelCase";>CamelCase</a>.</li>
+ <li>When creating documentation for a package you should follow the
main <a href="{{ url_for('guidelines_documentation') }}">Documentation
Guidelines</a>.</li>
+ <li>There are some <a href="{{
url_for('guidelines_documentation_help') }}">Help Text Guidelines</a> to follow
if you are writing or changing help text.</li>
+ <li>If submitting a Howto for approval, then please make sure you've
followed the <a href="{{ url_for('guidelines_documentation_howto') }}">Howto
Guidelines</a>.</li>
</ul>
</div>
<div class="subsection">
diff -r 66a9b14309ac -r 671443acd8a0 templates/guidelines/code.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/templates/guidelines/code.html Wed Dec 30 16:04:36 2020 +0000
@@ -0,0 +1,74 @@
+{% set title = "Coding Guidelines" %}
+{% set description = "Coding guidelines for Tryton" %}
+{% set keywords = ["development", "coding", "guidelines", "python", "xml"] %}
+{% set toc = [
+ ("Code Style", 'code-style', [
+ ("Python", 'python', None),
+ ("XML", 'xml', None),
+ ]),
+ ("Best Practices", 'best-practices', [
+ ("Naming of modules, classes, variables", 'naming', None),
+ ]),
+ ]
+%}
+{% extends "layout-toc.html" %}
+{% from "utils.html" import background with context %}
+{% block style %}
+{{ super() }}
+{{ background('banner-develop') }}
+{% endblock %}
+{% block content %}
+<section class="section section-banner background-banner-develop filter
filter-primary text-center lazy">
+ <div class="container">
+ <h1 class="mb-0 text-white position-relative z-1">{{ title }}</h1>
+ </div>
+</section>
+{{ super() }}
+{% endblock content %}
+
+{% block main %}
+<div class="subsection">
+ <h2 id="code-style">Code Style</h2>
+ <p>The Tryton Project strongly recommends the following code style.</p>
+ <h3 id="python">Python</h3>
+ <p>Code style, in general, follows <a
href="https://www.python.org/dev/peps/pep-0008/";>PEP 8</a>:</p>
+ <ul>
+ <li>Use 4 spaces for indentation.</li>
+ <li>Avoid the usage of <span class="text-monospace">from M import
*</span>.</li>
+ <li>If unsure about conformity use <a
href="https://pypi.org/project/flake8/";>flake8</a> to check the code (with
option <span
class="text-monospace">ignore=E123,E124,E126,E128,E741,W503</span>).</li>
+ <li>Breaking lines:
+ <ul>
+ <li>Use 4 spaces per bracket pair.</li>
+ <li>Prefer parenthesis over backslash.</li>
+ </ul>
+ </li>
+ </ul>
+ <h3 id="xml">XML</h3>
+ <ul>
+ <li>Use 4 spaces for indentation.</li>
+ <li>No 80 columns limitation.</li>
+ <li>Opening tag on single line or one attribute per line.</li>
+ </ul>
+ <h2 id="best-practices">Best Practices</h2>
+ <p>These best practices help keep the code consistent.</p>
+ <ul>
+ <li>Use doc-strings and comments in your code.</li>
+ <li>Never pass keyword arguments as positional arguments when calling
a method.</li>
+ <li>In the very beginning (right under the doc-string) of a method
definition, define all pool objects that will be used (<span
class="text-monospace">pool.get(...)</span>).</li>
+ </ul>
+ <h3 id="naming">Naming of modules, classes, variables</h3>
+ <ul>
+ <li>A name should be as descriptive and as short as possible.</li>
+ <li>Avoid unnecessary duplication of names.</li>
+ <li>Naming structure of a model or module must follow these rules:
+ <ul>
+ <li>First part of the name is the general function of the
module or model,</li>
+ <li>after this come the less general parts of the name (i.e.
the more specific name parts) for the module or model</li>
+ <li>If you are unsure with naming, please ask first on the <a
href="{{ url_for('forum', _anchor='irc') }}">#tryton channel</a></li>
+ </ul>
+ </li>
+ <li>For modules and method names use an underscore to separate the
parts of name.</li>
+ <li>For naming classes use <a
href="https://en.wikipedia.org/wiki/CamelCase";>CamelCase</a>.</li>
+ </ul>
+</div>
+{% endblock main %}
diff -r 66a9b14309ac -r 671443acd8a0 templates/guidelines/documentation.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/templates/guidelines/documentation.html Wed Dec 30 16:04:36 2020 +0000
@@ -0,0 +1,238 @@
+{% set title = "Documentation Guidelines" %}
+{% set description = "Documentation guidelines for Tryton" %}
+{% set keywords = ["development", "documentation", "guidelines",
"restructuredtext", "sphinx"] %}
+{% set toc = [
+ ("Purpose", 'purpose', None),
+ ("General Style", 'general-style', [
+ ("Use of Whitespace", 'use-of-whitespace', None),
+ ("Line Length", 'line-length', None),
+ ("Capitalisation", 'capitalisation', None),
+ ("Sections", 'sections', None),
+ ("Anchors", 'anchors', None),
+ ("Links", 'links', None),
+ ("Inline Markup", 'inline-markup', None),
+ ]),
+ ("Structure", 'structure', [
+ ("Modules", 'modules', None),
+ ]),
+ ]
+%}
+{% extends "layout-toc.html" %}
+{% from "utils.html" import background with context %}
+{% block style %}
+{{ super() }}
+{{ background('banner-document') }}
+{% endblock %}
+{% block content %}
+<section class="section section-banner background-banner-document filter
filter-primary text-center lazy">
+ <div class="container">
+ <h1 class="mb-0 text-white position-relative z-1">{{ title }}</h1>
+ </div>
+</section>
+{{ super() }}
+{% endblock content %}
+
+{% block main %}
+<div class="subsection">
+ <h2 id="purpose">Purpose</h2>
+ <p>The main Tryton documentation is written using <a
href="https://docutils.sourceforge.io/rst.html";>reStructuredText</a> and is
converted into a variety of different formats using <a
href="https://www.sphinx-doc.org/";>Sphinx</a>.</p>
+ <p>For most things this style guide aims to be consistent with the <a
href="https://devguide.python.org/documenting/#style-guide";>Python style
guide</a>.</p>
+ <p>Some of the most important points are also mentioned here along with
any areas that are different, or are specific to Tryton.</p>
+ <p>
+ Wherever appropriate you should try follow the rules given in this
document.
+ If something is not mentioned here, but the Python style guide mentions
it, then try and follow that.
+ If neither have an opinion on it, but it is already done a particular way
in the existing documentation then try and follow that.
+ The real aim is to have a consistent structure and style for all the
documentation.</p>
+</div>
+<div class="subsection">
+ <h2 id="general-style">General Style</h2>
+ <h3 id="use-of-whitespace">Use of Whitespace</h3>
+ <p>The key things to take note of are:</p>
+ <ul>
+ <li>Start each sentence on a new line.
+ This results in simpler code reviews and diffs when changes need
to be made in the future.</li>
+ <li>Use a standard indentation of 3 spaces, with no tabs.</li>
+ <li>List's contents should be indented so that it lines up with the
start of the text in the first line.</li>
+ <li>Blocks of code should be indented the way they would normally be
indented.</li>
+ </ul>
+ <p>For example:</p>
+ <pre><code class="plaintext">A sentence should end with a full stop. There
should be a single space
+before the start of the next sentence.
+
+Indentation
+ The blank space between the start of a line and where the text
+ starts.
+
+ .. note::
+
+ This is where the text should normally be indented to.
+
+* This is a list item
+ with two lines of text.
+
+ * And a sub list
+
+#. This is a numbered list item
+ with multiple lines of
+ text.</code></pre>
+ <h3 id="line-length">Line Length</h3>
+ <p>
+ The maximum line length for normal text is 79 characters.
+ This can be exceeded for tables and long links that are not part of a
paragraph.</p>
+ <h3 id="capitalisation">Capitalisation</h3>
+ <p>Try and follow the rules in the Python style guide, so:</p>
+ <ul>
+ <li>Use sentence case for section titles.</li>
+ <li>Except for the names of objects. In section titles these should
use title case.</li>
+ </ul>
+ <p>To ensure consistency for certain words and terms always use:</p>
+ <dl class="bg-light p-2">
+ <dt>Tryton</dt>
+ <dd class="pl-4">This is always capitalised, unless referring to the
<span class="text-monospace">tryton</span> command for the desktop client.</dd>
+ </dl>
+ <p>
+ Also avoid using the word ERP after Tryton.
+ This is because Tryton can be used for more than just enterprise resource
planning.</p>
+ <h3 id="sections">Sections</h3>
+ <p>Section heading styles follow the Python style guide:</p>
+ <ul>
+ <li><code>#</code> with overline, for the project or module title in
the <span class="text-monospace">index.rst</span> file</li>
+ <li><code>*</code> with overline, for the main titles in the other
main <span class="text-monospace">.rst</span> files or subdirectory <span
class="text-monospace">index.rst</span> files</li>
+ <li><code>=</code>, for sections</li>
+ <li><code>-</code>, for subsections</li>
+ <li><code>^</code>, for subsubsections</li>
+ <li><code>"</code>, for paragraphs</li>
+ </ul>
+ <h3 id="anchors">Anchors</h3>
+ <p>In order to make it easy to link the documentation together, and find
Tryton objects based on their <code>__name__</code> use explicitly defined
anchors.</p>
+ <ul>
+ <li><p>For all <mark>concepts</mark>, <mark>models</mark>,
<mark>wizards</mark>, <mark>reports</mark> and <mark>config</mark> settings
place an anchor before their title using the object's type followed by a dash
(<code>-</code>), then the object's full <code>__name__</code>.</p>
+ <p>So, for example, for the purchase model and report you would
use:</p>
+ <pre><code class="plaintext">.. _model-purchase.purchase:
+
+Purchase Model
+==============
+
+.. _report-purchase.purchase:
+
+Purchase Report
+---------------</code></pre></li>
+ <li><p>
+ Each setup and usage step should also have an anchor defined.
+ For these the anchor should match the title, so that they can be
linked to without needing to duplicate the title in the reference link.</p></li>
+ </ul>
+ <h3 id="links">Links</h3>
+ <p>
+ It's good to provide the reader with links to any concepts or instructions
that are described elsewhere and relevant to the item being documented.
+ <ul>
+ <li>The <code>default_role</code> is set to <code>ref</code>.
+ This allows links to be created without needing to prefix them
with <code>:ref:</code>.</li>
+ <li>Add a link each time an item is first mentioned within a section.
+ This is because the reader may have just jumped into the document
at the current section and not seen any links in earlier parts of the
document.</li>
+ <li>When an item is mentioned more than once extra mentions can be
styled using the <code>*Item*</code> format.
+ This should also be used instead of creating a link when
mentioning the current section.</li>
+ <li>Links should be created with an explicit title, for example
<code>`Link Title <target>`</code>.</li>
+ <li>The documentation uses <a
href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html";>intersphinx</a>
to allow links to other module's documentation.
+ When linking to targets in other modules always prefix the target
with the module name followed by a colon (<code>:</code>) for example
<code>`Link Title <module:target>`</code>.</li>
+ <li>You can also create a link to another module by linking to that
module's <span class="text-monospace">index.rst</span> file.
+ For example: <pre><code class="plaintext">Services can be defined
in the :doc:`Product Module <product:index>`.</code></pre></li>
+ </ul>
+ <h3 id="inline-markup">Inline Markup</h3>
+ <p>Where available <a
href="https://docutils.sourceforge.io/docs/user/rst/quickref.html";>standard
reStructuredText markup</a> and <a
href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html";>Sphinx
roles</a> can be used (except in the <span
class="text-monospace">index.rst</span> file).</p>
+ <p>Literal values should always be surrounded by double backticks
(<code>``</code>) to avoid the value being interpreted as a reference by the
default role.</p>
+ <p>A few useful examples of standard roles include:</p>
+ <dl>
+ <dt><code>:abbr:`TST (Test Sphinx Thing)`</code></dt>
+ <dd class="pl-4">Used to define abbreviations.
+ The abbreviation definition can be given inside brackets and is
only shown as a tooltip.</dd>
+ <dt><code>:command:`trytond_import_countries`</code></dt>
+ <dd class="pl-4">Used for the name of commands or scripts.</dd>
+ <dt><code>:doc:`Style Guide <style>`</code></dt>
+ <dd class="pl-4">Used to link to a documentation file.</dd>
+ <dt><code>:file:`modules/{module_name}/doc/index.rst`</code></dt>
+ <dd class="pl-4">Used for filenames.
+ Parts that may vary can be included with <mark>{variable}</mark>
syntax, these are displayed differently to indicate that they should be
replaced by the correct value when used.</dd>
+ <dt><code>:guilabel:`Open related records`</code></dt>
+ <dd class="pl-4">Used for any element in the <abbr title="Graphical
User Interface">GUI</abbr>.
+ This includes button labels, window titles, menu names, and so
on.</dd>
+ <dt><code>:menuselection:`Administration --> Users -->
Users`</code></dt>
+ <dd class="pl-4">Used for menu items.
+ Each level is separated using <code>--></code>.
+ <p>
+ To create a <code>:menuselection:</code> item that is also a link
you need to use substitutions:</p>
+ <pre><code class="plaintext">This is found in the main menu:
+
+ |Menu --> Sub Menu --> Item|__.
+
+ .. |Menu --> Sub Menu --> Item| replace:: :menuselection:`Menu --> Sub Menu
--> Item`
+ __ https://example.com/</code></pre>
+ <p class="bg-info rounded p-2">
+ <span class="material-icons">warning</span>
+ Where possible try and put <code>:menuselection:</code> items in
an indented paragraph of their own so they won't break across lines.
+ If this is not possible then enclose them in <code>[</code>square
brackets<code>]</code> to help make them easier to read.</p></dd>
+ <dt><code>:rfc:`2324`</code></dt>
+ <dd class="pl-4">Used for links to Internet Request for Comments.
+ Just use the RFC's number.</dd>
+ </dl>
+</div>
+<div class="subsection">
+ <h2 id="structure">Structure</h2>
+ <h3 id="modules">Modules</h3>
+ <p>
+ A module's documentation should be placed inside the <span
class="text-monospace">doc</span> directory found in the module.
+ Depending on what the module does, and how it is structured you may need
some, or all, of the following files:</p>
+ <dl>
+ <dt class="text-monospace">conf.py</dt>
+ <dd class="pl-4"><p>
+ This file is required, and is the Sphinx configuration file.
+ It must be kept exactly the same as the <span
class="text-monospace">conf.py</span> files in the all the other
modules.</p></dd>
+ <dt class="text-monospace">index.rst</dt>
+ <dd class="pl-4"><p>
+ This file is also required and should include a basic description
of the module and a table of contents (<code>toctree</code> directive) that
links to the other files with a <code>maxdepth</code> of 2.</p>
+ <p class="bg-warning rounded p-2">
+ <span class="material-icons">warning</span>
+ In this file use only standard restructured text markup, do not
use any Sphinx specific roles or directives, except <code>toctree</code>.
+ This is because this file is used as the module's <span
class="text-monospace">README.rst</span>, and also as the distribution's
<code>long_description</code>.
+ It's contents is displayed on <a
href="https://pypi.org/";>PyPI</a>, and PyPI doesn't support Sphinx directives
and roles.
+ Using them will cause problems when packaging the module for
distribution.</p>
+ <p>
+ The reason it is okay to use a <code>toctree</code> directive is
because the build process knows about these and automatically strips them out
when building the distribution file.</p></dd>
+ <dt class="text-monospace">setup.rst</dt>
+ <dd class="pl-4"><p>
+ The aim of this file is to describe any setup that needs to be
done once a module has been activated.
+ Often this setup will need to be done by the user before the
module can be used properly.</p>
+ <p>
+ Add sections to this file that describe the setup that is required
and how it is done, for example <mark>"Doing a specific module setup
task"</mark>, or <mark>"Setting up the thing to do something"</mark>.</p></dd>
+ <dt class="text-monospace">usage.rst</dt>
+ <dd class="pl-4"><p>
+ The contents of this file are intended for users of the system.
+ So it should talk to these readers directly and you can refer to
them in the second person.
+ This means you can use sentences like <mark>"Your system ... then
you need to ..."</mark>.</p>
+ <p>
+ It should contain sections that provide instructions or guidance
on using a feature of the module, for example <mark>"Using the main feature in
the module"</mark>, or <mark>"Working with a specific part of the
module"</mark>.</p></dd>
+ <dt class="text-monospace">configuration.rst</dt>
+ <dd class="pl-4"><p>
+ This file should contain each of the server configuration settings
that the module provides.
+ Each configuration option should be described mentioning what it
is for, or what it does.</p></dd>
+ <dt class="text-monospace">design.rst</dt>
+ <dd class="pl-4"><p>
+ The design and structure of the module is described in this file.
+ Try and focus on the concepts that the module introduces or
extends.
+ Often these concepts are implemented in Tryton as models, but it
is the concepts and how they fit together that are important.</p>
+ <p>
+ Avoid specifically mentioning models, fields, or selection values
these are documented in the code with doc strings and <a href="{{
url_for('guidelines_documentation_help') }}">help text</a>.</p>
+ <p>
+ Wizards and reports should be documented in sections beneath the
concepts that they relate to.
+ If they are used with several different models then document them
as part of either the primary, or first, model that they relate to, and then
link to them from any other models that use them.</p></dd>
+ <dt class="text-monospace">reference.rst</dt>
+ <dd class="pl-4"><p>
+ This file is used to provide reference information for people who
are developing or working on the module.
+ It includes sections that document any APIs or routes the module
provides, as well as documentation on how to build or update parts of the
module.</p></dd>
+ </dl>
+ <p>
+ In some cases a large module may require lots of documentation.
+ It can make sense to split up these files into smaller parts.
+ To do this the file should be replaced with a directory of the same name,
but without the <span class="text-monospace">.rst</span> extension.
+ The separate files should be added to this directory, and there should be
an <span class="text-monospace">index.rst</span> file which contains a
<code>toctree</code> that includes the separate files.</p>
+</div>
+{% endblock main %}
diff -r 66a9b14309ac -r 671443acd8a0 templates/guidelines/help.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/templates/guidelines/help.html Wed Dec 30 16:04:36 2020 +0000
@@ -0,0 +1,130 @@
+{% set title = "Help Text Guidelines" %}
+{% set description = "Help text guidelines for Tryton" %}
+{% set keywords = ["development", "documentation", "guidelines", "help",
"text"] %}
+{% set toc = [
+ ("Purpose", 'purpose', None),
+ ("General Style", 'general-style', [
+ ("Language", 'language', None),
+ ("Formatting", 'formatting', None),
+ ]),
+ ("Standard Help Text", 'standard-help-text', [
+ ("Fields", 'standard-fields', None),
+ ]),
+ ]
+%}
+{% extends "layout-toc.html" %}
+{% from "utils.html" import background with context %}
+{% block style %}
+{{ super() }}
+{{ background('banner-document') }}
+{% endblock %}
+{% block content %}
+<section class="section section-banner background-banner-document filter
filter-primary text-center lazy">
+ <div class="container">
+ <h1 class="mb-0 text-white position-relative z-1">{{ title }}</h1>
+ </div>
+</section>
+{{ super() }}
+{% endblock content %}
+
+{% block main %}
+<div class="subsection">
+ <h2 id="purpose">Purpose</h2>
+ <p>The help messages for fields, buttons and selection values, which are
displayed as tooltips in the client, are very useful for new users who are
discovering Tryton and existing users who need to refresh their memory.<p>
+ <p>
+ These help messages are part of Tryton's documentation and are great
because they are easily displayed to users, at the time and place where they
need to see them.
+ They are also close to the code, as they are defined in the
<code>help</code> parameters to fields, which helps developers keep them up to
date, and allows them to be shown in the user's language.</p>
+ <p>These guidelines provide some clear rules on how to write this help
text, so it is kept consistent and accurate across the whole application.</p>
+ <p>The help text should answer the question:<p>
+ <p class="bg-light font-weight-bold p-2">What is this, or what is it
for?</p>
+ <p>If it is obvious what it is for, or what it does, then it is often
better not to add any help text.</p>
+</div>
+<div class="subsection">
+ <h2 id="general-style">General Style</h2>
+ <p>In general you should try and follow the <a
href="https://material.io/design/communication/writing.html";>material design
style guide</a>.</p>
+ <h3 id="language">Language</h3>
+ <ul>
+ <li>The help text is always written in English, Tryton will
automatically display it in the user's language if a translation for it is
available.</li>
+ <li>Write in complete sentences, starting with a capital letter and
ending with a full stop.</li>
+ <li>Try and write text that adds useful information in a clear,
accurate and concise way.
+ Normally help text will be no more that one or two lines long.</li>
+ </ul>
+ <h3 id="formatting">Formatting</h3>
+ <p>General formatting guidelines that are applicable to all types of help
text:</p>
+ <ul>
+ <li>Always use double quotes for help text.
+ In Tryton double quotes are normally used for human readable text,
and help text is designed to be read by humans.</li>
+ <li>If you need to add a line break it can be done using
<code>\n</code> in the help text.</li>
+ <li>Multi-line strings are concatenated without needing an operator
(<code>+</code>).</li>
+ <li>Indent multi-line help text so it all has the same level of
indentation:
+ <pre><code class="python">help="Multi-line help text should "
+"all have the same level of indentation."</code></pre></li>
+ <li>Break long strings after a whitespace character:
+ <pre><code class="python">help="You should break long "
+"strings after a whitespace,\n"
+"not before."</code></pre></li>
+ <li>Start each sentence on a new line:
+ <pre><code class="python">help="When using multiple sentences. "
+"Code reviews will be easier like this."</code></pre></li>
+ </ul>
+ <h4 id="buttons">Buttons</h4>
+ <ul>
+ <li>Help text for buttons should describe the action or impact of
pressing the button.</li>
+ </ul>
+ <h4 id="fields">Fields</h4>
+ <ul>
+ <li>Avoid using <mark>this</mark> or <mark>that</mark> when referring
to the field's value because the help text may be used when the value is not
visible:
+ <table>
+ <tr class="table-success">
+ <td>Use:</td>
+ <td>"The last date when the MODEL-NAME can be
used."</td></tr>
+ <tr class="table-danger">
+ <td>Avoid:</td>
+ <td>"Prevent usage after this date."</td></tr>
+ </table></li>
+ <li>On selection fields don't refer to the selection's options, these
may change depending on what modules are activated.</li>
+ <li>Help text for fields should describe either what is contained in
the field or what it is used for.
+ Avoid using verbs for these:
+ <table>
+ <tr class="table-success">
+ <td>Use:</td>
+ <td>"Used to group stock moves together."</td></tr>
+ <tr class="table-success">
+ <td>Use:</td>
+ <td>"The moves that put the stock away into the storage
area."</td></tr>
+ <tr class="table-danger">
+ <td>Avoid:</td>
+ <td>"Edit where to store the goods."</td></tr>
+ </table></li>
+ </ul>
+</div>
+<div class="subsection">
+ <h2 id="standard-help-text">Standard Help Text</h2>
+ <h3 id="standard-fields">Fields</h3>
+ <p>
+ Some fields implement general functionality and are used in many different
places in the same way.
+ To keep things consistent use one of the standard help text values for
these:</p>
+ <dl>
+ <dt>Name <span class="small">(name)</span>:</dt>
+ <dd class="pl-4 text-info">This should be pretty obvious and so no
help text is normally required.</dd>
+ <dt>Name <span class="small">(rec_name)</span>:</dt>
+ <dd class="pl-4">The main identifier for the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Parent:</dt>
+ <dd class="pl-4">Used to add structure above the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Children:</dt>
+ <dd class="pl-4">Used to add structure below the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Number:</dt>
+ <dd class="pl-4">The main identifier for the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Code:</dt>
+ <dd class="pl-4">The internal identifier for the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Reference:</dt>
+ <dd class="pl-4">The external identifier for the
<mark>MODEL-NAME</mark>.</dd>
+ <dt>Origin:</dt>
+ <dd class="pl-4">The source of the <mark>MODEL-NAME</mark>.</dd>
+ <dt>Company:</dt>
+ <dd class="pl-4">The company that the <mark>MODEL-NAME</mark> is
associated with.</dd>
+ <dt>State:</dt>
+ <dd class="pl-4">The current state of the <mark>MODEL-NAME</mark>.</dd>
+ </dl>
+</div>
+{% endblock main %}
diff -r 66a9b14309ac -r 671443acd8a0 templates/guidelines/howto.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/templates/guidelines/howto.html Wed Dec 30 16:04:36 2020 +0000
@@ -0,0 +1,90 @@
+{% set title = "Howto Documentation Guidelines" %}
+{% set description = "Howto documentation guidelines for Tryton" %}
+{% set keywords = ["development", "documentation", "guidelines", "howto"] %}
+{% set toc = [
+ ("Purpose", 'purpose', None),
+ ("General Style", 'general-style', [
+ ("Consistency", 'consistency', None),
+ ("Audience", 'audience', None),
+ ("Formatting", 'formatting', None),
+ ("Sections", 'sections', None),
+ ("Table of Contents", 'table-of-contents', None),
+ ]),
+ ]
+%}
+{% extends "layout-toc.html" %}
+{% from "utils.html" import background with context %}
+{% block style %}
+{{ super() }}
+{{ background('banner-document') }}
+{% endblock %}
+{% block content %}
+<section class="section section-banner background-banner-document filter
filter-primary text-center lazy">
+ <div class="container">
+ <h1 class="mb-0 text-white position-relative z-1">{{ title }}</h1>
+ </div>
+</section>
+{{ super() }}
+{% endblock content %}
+
+{% block main %}
+<div class="subsection">
+ <h2 id="purpose">Purpose</h2>
+ <p>
+ The <a href="https://discuss.tryton.org/c/howto";>Howto categories</a> are
the right place to document more complex tasks.
+ These are for things that involve multiple different modules, or need to
describe concepts and go into lots of detail.</p>
+ <p>A howto is ideal for things like:</p>
+ <ul>
+ <li><a
href="https://discuss.tryton.org/t/how-to-run-tryton-using-docker/3200";>How to
run Tryton using Docker</a>
+ (what steps are required, what commands need to be run and what
does each one do)</li>
+ <li>How to import initial stock
+ (how to create products, set proper cost prices, and create the
initial internal shipment from the supplier location)</li>
+ <li>How to organise warehouse locations
+ (including what strategies can be used, what are their pros and
cons, what performance concerns are there and what can be done to avoid
them)</li>
+ </ul>
+ <p>
+ Each howto should focus on a single topic, links to related topics, or
other documentation can always be included when needed.
+ It is much better to add documentation into the right place, and then link
to it, to avoid duplicating documentation.</p>
+</div>
+<div class="subsection">
+ <h2 id="general-style">General Style</h2>
+ <h3 id="consistency">Consistency</h3>
+ <p>
+ Try and be consistent with how other howtos have been written.
+ Read through some of the existing howtos to get an idea of their style and
how they have been structured.
+ This will make all the howtos feel familiar to the readers and help them
get the most out of them.</p>
+ <h3 id="audience">Audience</h3>
+ <p>
+ When writing your howto try and remember which audience the document is
intended for.
+ There are separate sub-categories for different audiences so try and
submit your howto into the right place.</p>
+ <h3 id="formatting">Formatting</h3>
+ <p>
+ The editor allows you to format the howto as required.
+ It has buttons that can make text bold or italic, and allows you to insert
things like links, bullet and numbered lists.
+ Use these as appropriate.
+ <p class="bg-info rounded p-2">
+ <span class="material-icons">warning</span>
+ You may want to write your howto offline, and then copy and paste it when
you are ready to submit it.
+ If you are doing this then you can use the editor to see how the different
styles are represented in plain text.</p>
+ <h3 id="sections">Sections</h3>
+ <p>Ideally the howto should be structured in a logical way, with its parts
split up into appropriate sections and subsections.</p>
+ <p>
+ Section are introduced by a section title that uses one or more <span
class="text-monospace">#</span> symbols at the start of the line.
+ The number of <span class="text-monospace">#</span> symbols indicates the
level of the section.</p>
+ <p>For example:</p>
+ <pre><code class="plaintext"># Main Section
+
+## Subsection
+
+## Subsection
+
+### Subsubsection
+
+# Next Section</code></pre>
+ <h3 id="table-of-contents">Table of Contents</h3>
+ <p>
+ It is often a good idea to add a table of contents to the howto.
+ This will be automatically generated from the howto's sections if you
include, on the first line:</p>
+ <pre><code class="html"><div
data-theme-toc="true"></div></code></pre>
+</div>
+{% endblock main %}
