Writing Documentation

You can improve MyPaint by making instructions for people using and people making it. Good documentation is vital for everyone. Any sort of improvement, including fixing typos and improving readability, is greatly appreciated.

Want to help improve our documentation but don’t know where to start? Our issue tracker contains problems with the website and documentation. Use our git workflow when contributing improvements/fixes.

Tone & Writing Style

• Readers visit a page for a reason, understand that reason when writing a page.
• Use informative, but concise language.
  • Avoid large paragraphs when possible.
• Write using language understandable by a 12 to 14 year old.
• Do not assume readers’ level of technical or artistic skill.
  • e.g. Avoid using “just” or “simply” when giving instructions.
• Use your preferred dialect of English, as long as it’s clearly understood by most English readers.
• Page titles and headings should be in title case.

Translating Pages

If a page is complete, please consider translating it into other languages. MyPaint’s contributor documentation aims to be a single source of truth, so decidedlly not translating it reduces overhead.

Translate a page by prepending the .md extension with a language code. e.g. to localise this page to Japanese, create a page named documentation.ja.md.

Please also consider translating MyPaint (the program).

Developer Documentation

Poor or missing documentation is an obstacle to new contributors, you can help prevent this by writing documentation.

If you are new to technical writing, here are some resources to get you started:

• MDN Web Docs’ blog post
• Google’s courses
• FreeCodeCamp’s articles

Backend

Backend docs exist for two reasons, to:

1. Help new developers understand MyPaint’s general design as quickly as possible.
2. Scope files/directories by describing them.

They are presented to the reader as:

1. Here’s a file/concept.
2. This is the gist of what you need to know.
3. You’re now prepared to read through the code and understand the specifics.

The most detailed documentation for the project will always be contained within source code.

UX/UI

GUI changes are drafted in the docs, and then applied per those specifications in the program.

Using Hugo

This section details how to create and modify pages for this website. The MyPaint website is created using Hugo, a static site generator. Pages are written in Markdown (here’s a guide).

Quick Start

1. At the left side of this page, there is an aside menu with the “Page Information” heading.
2. Under the “Page Information” heading, there is a link to the source markdown file for this page. Click it.
3. Start getting your bearings by comparing what you see on the source file to what you see on this page.

Conventions

When creating or modifying *.md files:

• Break lines before the word that starts after the 80th column
• Pages have summaries generated from page content or front matter. They may be created:
  1. Automatically at the 70th word
  2. At the position of the <!--more--> tag in the content.
  3. In front matter, using the summary key.
  • Try to avoid the first case here and instead use case 2 or 3.

Build the Site Locally

1. Install hugo-extended, dart sass, and git-lfs
2. Clone the website repository
3. Run git submodule update --init
4. Run hugo or hugo server

Update Submodules

When the website-theme or other submodules are updated, use git submodule update --recursive --remote to reflect the changes in your development environment.

Adding Content

Page content is stored in the pages directory. To add a new page to the website, type hugo new content pages/path/to/filename.md.

Main page image: Page bundles may include a file named index.jpg or index.png, preferrably accompanied with imgAlt front matter. Such image files will:

• Render the image behind the page title.
• Add meta image tags (for e.g. OpenGraph)

Front Matter

Front matter is used to store a page’s metadata. This site’s front matter is written in TOML.

List Pages

Front matter specific to list pages

Shortcodes

Shortcodes extend markdown with custom HTML templates.

Useful Hugo Builtin Shortcodes

Custom Shortcodes

Documenting Python

Docstrings

We seem to be settling on Sphinx’s autodoc syntax for writing docstrings. Where it doesn’t contradict, please follow PEP 257 too.

Python code should always have docstrings describing what a public function or class does. We would like to use Sphinx’s autodoc to generate API documentation one day, but conventions have not yet been settled for it. For now, please document parameters using Sphinx-style info field lists, and try not to use too much additional ReStructuredText markup.

class Example (_ExampleBase):
    """Demonstrative example class."""

    def add_two(self, n1, n2):
        """Adds two numbers, or other objects.

        :param object n1: The first object to addify.
        :param object n2: The second object to addulate.
        :returns: The summified results of the two arguments.

        Any kind of object can be added provided it's supported
        by the builtin "+" operator. You might as well use that.

        """
        return n1 + n2

When it’s not obvious what a bit of code is doing, add comments to explain why you are doing something.