Application documentation Documentation Release 0.1 Daniele Procida June 14, 2016
Contents 1 Tutorial 3 1.1 Setting up................................................. 3 1.2 Configuring the documentation..................................... 4 1.3 Spelling checks.............................................. 5 1.4 Starter files................................................ 7 1.5 Publishing on Read the Docs....................................... 8 2 Standards 9 2.1 General standards............................................ 9 2.2 Structure................................................. 9 2.3 Markup.................................................. 12 2.4 The README file and GitHub fields.................................. 13 i
ii
This document contains guidelines and examples for documentation in Divio/Aldryn application projects. Start with the tutorial sections, and use the standards guidance to check that your documentation conforms to them. Contents 1
2 Contents
CHAPTER 1 Tutorial Follow the steps in the tutorials to build a complete set of documentation for a project. Where appropriate refer to the guidance in the Standards sections. 1.1 Setting up If your project doesn t already have a docs directory for Sphinx-based documentation, you ll need to set it up. Make sure that you have the latest version of Sphinx: pip install --upgrade sphinx 1.1.1 Initialise the documentation Then in the root of your project, issue the command to initialise the documentation: sphinx-quickstart You ll be asked a series of questions. You can accept most of the default values, but some will need to be set explicitly. Documentation is always in docs: > Root path for the documentation [.]: docs Give the full name of the project, not its Python name (e.g. django CMS, not django-cms): > Project name: Application documentation The author is Divio AG if this is a Divio project: > Author name(s): Divio AG Enter the project version numbers: > Project version: 0.1 > Project release [0.1]: Later we will change the documentation s conf.py so that these values are picked up automatically from the code. We want to enable to-do notes: 3
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y Your docs directory now exists in docs, complete with an index.rst file. 1.2 Configuring the documentation Before building your documentation, you need to make some minor manual changes to the conf.py file that is automatically created by sphinx-quickstart. 1.2.1 Theme At the top of conf.py ensure that sys is imported as well as os. Find the section: # -- Options for HTML output ---------------------------------------------- html_theme = 'alabaster' Alabaster is a plain and perfectly functional theme, but both on the Read the Docs website and when building locally, you will want your documentation to use the sphinx_rtd_theme. In place of the line setting the html_theme, add: # on_rtd is whether we are on readthedocs.org on_rtd = os.environ.get('readthedocs', None) == 'True' if not on_rtd: # only import and set the theme if we're building docs locally try: import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] except: html_theme = 'default' When building locally, this will use the sphinx_rtd_theme if it s available, and if not will use the default theme. It will always use sphinx_rtd_theme on the Read the Docs. sphinx_rtd_theme should be available, so add it to your application s requirements. 1.2.2 Automatic version detection When we first used sphinx-quickstart, we provided version numbers. It s more convenient to extract these automatically from the software itself. You ll find lines in conf.py that set the version and release. Replace these with: try: application_name # substitute the actual application name here except ImportError: version = release = "undefined" else: version = application_name. version # substitute the actual application name here # The full version, including alpha/beta/rc tags. release = application_name. version # substitute the actual application name here 4 Chapter 1. Tutorial
This tries to import the application, and extract the version information (obviously, this requires your application to provide this information in the first place). If it can t import the application, it ll just use a value undefined, which is fine for local building. 1.3 Spelling checks We want to be able to have automated spelling checking for the documentation, that developers can use to help when writing it, and also that runs on Travis, so that we can see at a glance whether a pull request containing documentation changes is free of spelling errors. 1.3.1 Sphinx configuration Add the following to the end of the docs/conf.py file: # -- Options for spelling checks ---------------------------------------------- # Spelling check needs an additional module that is not installed by default. # Add it only if spelling check is requested so docs can be generated without it. if 'spelling' in sys.argv: extensions.append("sphinxcontrib.spelling") # Spelling language. spelling_lang = 'en_gb' # Location of word list. spelling_word_list_filename = 'spelling_wordlist' spelling_ignore_pypi_package_names = True 1.3.2 Add Makefile command Warning: In a Makefile any whitespace at the start of a line must be a tab. If you use spaces, you ll get an unfriendly error message: Makefile:196: *** missing separator. Stop. In the Makefile, add: @echo " spelling to check for typos in documentation" to the help section, and: spelling: $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) _build/spelling @echo @echo "Check finished. Wrong words can be found in " \ "_build/spelling/output.txt." to the end of the same file (check of course that similar lines have not already been added). 1.3.3 Installation of spelling dependencies Add: 1.3. Spelling checks 5
sphinx sphinxcontrib-spelling pyenchant to the project s test_requirements.txt file (or whichever file is responsible for installing dependencies required for testing). Install them: pip install -r test_requirements.txt # or whatever the file is called You will need to install enchant too, if it s not already installed. The easy way to check is to run make spelling from the docs directory. If it runs successfully, you don t need to do anything, but if not you will have to install enchant for your system. For example, on OS X: brew install enchant or Debian Linux: apt-get install enchant 1.3.4 Set up the word-list Numerous words that you are likely to need to use are known to be flagged as errors against various default dictionaries, including Travis s. To avoid having to identify and add all these for each project, copy the spelling_wordlist file from the documentation starter files to the docs directory. Run the spelling checks Now you should be able to run make spelling from the docs directory. With luck, it will exit without errors (build succeeded.), but if not, it will create a file output.txt listing the words it doesn t recognise, and where they occur. Words that are not in the built-in dictionary can be added to docs/spelling_wordlist. If you are certain that a word is incorrectly flagged as misspelt, add it to the spelling_wordlist document, in alphabetical order. Please do not add new words unless you are sure they should be in there. If you find technical terms are being flagged, please check that you have capitalised them correctly - javascript and css are incorrect spellings for example. Commands and special names (of classes, modules, etc) in double backticks - - will not caught by the spelling checker. 1.3.5 Set up spelling checks on Travis Just like your local environment, Travis will also need to have enchant installed. Add: addons: apt: packages: - enchant to your project s travis.yml file. 6 Chapter 1. Tutorial
1.3.6 Add the documentation build and spelling checks to the test suite Todo Add a documentation test class to the test suite. See https://github.com/evildmp/djangocms/blob/316328a38941e408c2af279cbcd7260fc2ab2746/cms/tests/test_docs.py for django CMS s example. 1.4 Starter files A set of documentation starter files is provided in a GitHub repository. They won t be suitable for every project, but they can help make a quick start, especially if you are not sure how to begin. 1.4.1 How to use the starter files For a brand-new project Follow the directions for setting up and then configuring your documentation. git clone git@github.com:divio/application-documentation-starter-files.git (i.e. the repository of starter files) into another directory. Copy the contents of (i.e. not the directory itself) the starter-docs directory of this project into your project s docs directory. Copy the STARTER-README.rst file into your project, and rename it to README.rst For a project that has some of these files already Your work will be a little harder; you ll have to choose which files to copy/overwrite/rewrite individually. Search-and-replace The starter files contain strings you can replace with the correct ones for your application. Do a search-and-replace on them: application-full-name: the full, human name of the application - e.g. Aldryn Spaceship application-package-name: the package name - e.g. aldryn-spaceship application-python-name: the Python name - e.g. aldryn_spaceship application-repo-url: the URL of the repository - e.g. https://github.com/aldryn/aldryn-spaceship After your search and replaces, you will still need to go through the documentation to check and correct: line wrapping changes underline/overline of headings 1.4. Starter files 7
Provide actual content Throughout the starter files you will see text in square brackets, e.g. [describe what the application does] - these are things you need to do. 1.5 Publishing on Read the Docs These steps are only possible if your project is Public on GitHub. Go to your account on Read the docs and hit Import a project, then Import from GitHub. Your project should be listed; hit its Create button. Generally, you can leave all options on their default settings. Hit Next, then Build. In a few moments, your documentation should be successfully built and available. Note that the Build page on Read the Docs does not automatically update; you will need to refresh it. Hit View to see your published documentation, and all the typos and mistakes that you missed when you were proofreading it locally. Future pushes to GitHub will rebuild the documentation automatically. 8 Chapter 1. Tutorial
CHAPTER 2 Standards These sections contains guidelines. 2.1 General standards Documentation should be: structured correctly written using valid Sphinx/restructuredText syntax (see Markup for specifics) in files with the extension.rst wrapped at 100 characters per line written in English, using British English spelling and punctuation accessible - you should assume the reader to be moderately familiar with Python and Django, but not anything else. Link to documentation of libraries you use, for example, even if they are obvious to you Your documentation should be reviewed before it is committed, just like code. 2.1.1 English standards Not everyone is very confident about being able to write English to an appropriate standard for documentation, and even if they are, they might still not be sure about what spelling and punctuation standards to use. In this case, don t worry. The only important thing is to make sure that someone in the documentation team reviews your text. Similarly, you don t need to worry about writing beautiful or elegant English. In fact, don t try to make it correct: just make it as simple and clear as possible - and ask for a documentation review. As long as your text is understandable, it can easily be rewritten to conform with standards, so don t hesitate to write down the basic information and push it to a branch where someone can do any necessary further work on it. 2.2 Structure All Divio/Aldryn documentation should share as far as possible a common overall structure, with an index.rst file at the root of each directory. A typical project might contain: 9
docs/ index.rst introduction/ index.rst installation.rst basic_usage.rst reference/ index.rst user/ index.rst 2.2.1 Home index.rst: the root page of the documentation This should contain a brief description of the application, and links to its GitHub repository and key related sites (such as django CMS or Aldryn). It will typically share some of the same content as the README. 2.2.2 Introduction introduction/: step-by-step, beginning-to-end tutorials to get users up and running These tutorials must lead the user all the way to an end-point, in such a way that even if they barely understand what is happening, simply by following the steps they will be left with a successful, working result. The point of the Introduction is not to explain, but to lead the user through some simple steps. Installation introduction/installation.rst The Installation section needs to be reasonably comprehensive. Example: Aldryn Jobs installation. The Installation section is required. Basic usage introduction/basic_usage.rst This section describes some minimal steps required actually to do something with the software, the steps you d expect the site administrator to do to set it up within the Django admin, but not the ordinary content editor. Example: Aldryn Jobs basic usage. Unless these steps are unnecessary, or are completely obvious, this section is required. 2.2.3 How-to guides how_to/: step-by-step guides covering more advanced development If your documentation has some more free-form guides, that cover key steps in some process but not all of them, they should go into the how-to section. 10 Chapter 2. Standards
The how-to section is optional. 2.2.4 Key topics topics/: discussions and explanations of key parts of the system The topics section is optional. 2.2.5 Reference reference/: technical reference for APIs, key models and so on The topics section is optional, but recommended if APIs and models are complex enough to have several options that need to spelled out. Example: Aldryn Jobs reference. 2.2.6 Development & community contributing/ Not usually required; generally, a note in the README and in the main index.rst will suffice. 2.2.7 Release notes & upgrade information upgrade/ Strongly recommended. 2.2.8 Using <name of application> user/: guides for using rather than setting up or developing for the software The user documentation should as nearly as possible be a stand-alone section, so that an end-user who is not a developer finds it useful. Note: The introduction/basic_usage.rst section should have left the system in a state to make this possible. See for example the Aldryn Jobs documentation, in which the Using Aldryn Jobs section assumes that the Introduction has configured the basics in the admin. The user-facing documentation needs to be written for a user, not simply for a developer or technical expert who happens to be using it. It should describe the interface the user will see, the actions they can take, and the effects that will follow. It should not describe what happens behind the scenes, and it should not rely on technical terms in its explanations (explanations in general belong in the Key topics section). As far as possible, the user documentation needs to take the user through simple steps of operation so that they can see how to achieve basic things with it. 2.2. Structure 11
2.3 Markup 2.3.1 Sections Use two carriage returns before a new section. Headings should be marked up as follows: ########## Page title ########## ******* heading ******* sub-heading =========== sub-sub-heading --------------- sub-sub-sub-heading ^^^^^^^^^^^^^^^^^^^ sub-sub-sub-sub-heading """"""""""""""""""""""" 2.3.2 Inline markup use backticks - - for: literals: The ``cms.models.pagemodel`` contains several important methods. file names: Before you start, edit ``settings.py``. names of fields and other specific items in the Admin interface: Edit the ``Redirect`` field. use emphasis - *Home* - around: the names of available options in or parts of the Admin: To hide and show the *Toolbar*, use the... the names of important modes or states:... in order to switch to *Edit mode*. values in or of fields: Enter *Home* in the field. 12 Chapter 2. Standards
use strong emphasis - ** - around: buttons that perform an action: Hit **Save as draft**. Rules for using technical words There should be one consistent way of rendering any technical word, depending on its context. Please follow these rules: in general use, simply use the word as if it were any ordinary word, with no capitalisation or highlighting: Your placeholder can now be used. at the start of sentences or titles, capitalise in the usual way: Placeholder management guide when introducing the term for the the first time, or for the first time in a document, you may highlight it to draw attention to it: Placeholders are special model fields. when the word refers specifically to an object in the code, highlight it as a literal: Placeholder methods can be overwritten as required - when appropriate, link the term to further reference documentation as well as simply highlighting it. References Create (.. _testing:) and use (:ref: testing ) internal cross-references liberally. Use absolute links to other documentation pages - :doc: /how_to/toolbar - rather than relative links - :doc: /../toolbar. This makes it easier to run search-and-replaces when items are moved in the structure. 2.4 The README file and GitHub fields 2.4.1 README.rst The README file should be written in RST. Typically it will repeat much the same information that is in the root index.rst file (see Structure). You can also add badges for CI and so on. It should also contain a brief note about how to contribute. Make sure it contains the following text, or something very similar: ************ Contributing ************ <name of application> is a an open-source project. We'll be delighted to receive your feedback in the form of issues and pull requests. Before submitting your pull request, please review our `guidelines for Aldryn Addons <http://docs.aldryn.com/en/latest/reference/addons/index.html>`_. It should have a description of requirements, for example: 2.4. The README file and GitHub fields 13
************ Requirements ************ * django CMS 3.0.12 or later * Django 1.6 or 1.7 See Aldryn Jobs for an example. 2.4.2 GitHub On GitHub, it s important to complete: the Description field the link field, referring to the project s website, or a project page if one exists, or at least to its documentation 14 Chapter 2. Standards