How to document your extension¶

So you've written an extension. Awesome! Now you want to add some documentation to help people use it. Great! Maybe you even want some docs for other developers working on it too. Very good. This page will help you set up your own documentation guide (just like this Developer Guide) for your extension.

Example: CiviVolunteer

For a fully-featured working example of extension documentation we can look at CiviVolunteer.

Read the published CiviVolunteer guide
Inspect the following source code to see how it's made:
- /docs/ within the project repo (to store all the content in markdown files)
- /mkdocs.yml within the project repo (to specify guide structure)
- volunteer.yml within the docs-books repo (to specify how the guide is to be published)

Overview¶

Here are the basic steps (and each one is explained in more detail later on this page.)

You use the git repo for your extension to store its documentation.
You store the content in markdown files within a docs directory in your project.
You use git branches just like you normally would, with that docs directory sitting there in every branch.
You put one file at the root level of your project, mkdocs.yml to configure some of the high-level details of your book.
You use MkDocs locally to preview your guide.
When you're ready, you make a pull request on our publishing system's books repository to add the necessary configuration for your guide, so that it gets published to docs.civicrm.org.
You configure GitLab or GitHub to tell our publishing system when to publish updates to your guide.

Follow along in the steps below to get a guide up and running for your extension.

Set up `mkdocs.yml`¶

Create a new file called mkdocs.yml in the root level of your project with the following content:

site_name: Your Extension Name
repo_url: https://lab.civicrm.org/extensions/yourproject
edit_uri: https://lab.civicrm.org/extensions/yourproject_LANGUAGE/-/edit/master
site_description: 'A guide for the Your Extension Name extension.'
site_author: 'J Doe'
theme:
  name:
    material

nav:
- Home: index.md

markdown_extensions:
  - attr_list
  - admonition
  - def_list
  - pymdownx.highlight:
      guess_lang: False
  - toc:
      permalink: True
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.tilde
  - pymdownx.betterem
  - pymdownx.mark

plugins:
  - search:
      lang: en

Replace values on the first five lines with your own. The property edit_uri can be used if your edit URI and project repositor are not in the same place or you want to customise the edit_uri.

Edit URIs

If you define a custom edit URI the documentation system will not adjust it, you must provide the full edit URI. For example providing an edit_uri of https://lab.civicrm.org/extensions/yourproject_ES will result in errors when editing. You must determine the correct edit URI syntax - for GitLab this is https://lab.civicrm.org/extensions/yourproject_ES/-/edit/main

Do not provide edit_uri unless you know for certain that you need a different edit_uri if in doubt open an issue on the Docs Books repository. Leave everything else as-is (for now).

Decide what to do with your README file¶

The README file at the root of your repository is great for keeping some simple documentation that people will see when they visit your repo. But non-technical users can become confused when seeking docs landing on GitLab/GitHub.

When creating a docs guide, you have two options for how to deal with your README file:

Mirror README to a single-page guide¶

With this option, you basically keep documentation content in the README file, and create an MkDocs guide directly from that file. The content remains on GitHub when people visit your repo, and it also gets published on docs.civicrm.org — and you only have to edit it in one place. The downside is that you have to fit everything into one page.

Make sure you're using markdown formatting within the README file, and make sure the file is named README.md.
Create an MkDocs index file which is a symbolic link to your README file:
```
cd <project-root>
mkdir docs
cd docs
ln -s -T ../README.md index.md
```

Use a multi-page guide and a separate README file¶

With this option you have a very small README file and a separate MkDocs guide which can have multiple pages.

Add a docs directory at the root of your project.
Within that, add a new file index.md to use for your content.
Keep your README file, but don't store documentation in it. Just have it explain the bare bones of your project and link to your documentation (once it's published on docs.civicrm.org.)

Add content¶

Add some markdown content in docs/index.md.

You can add more pages by creating more markdown files and specifying these files under pages in mkdocs.yml.

Images

Your images should be stored in a folder named img inside your docs folder. E.g. docs/img/useful_img_showing_stuff.png.

Note

We have markdown coding standards and a documentation style guide. Adherence to these rules within your extensions docs is not currently required for publishing - it will become required in future.

Preview your guide¶

Now you should be able to run mkdocs serve from within your project directory to start previewing your content. See instructions here to get MkDocs set up.

Submit your guide to our publishing system¶

Once your guide is in good shape it's time to get it up on docs.civicrm.org.

Go to the repository for docs books
Click Fork, and if necessary choose your user as the destination of the fork.
Click on the + button to add a new file to the root directory within your fork.
For the file name, use something like foobar.yml, where "foobar" is your extension's short name. This is the name that will be used in the URL for your docs.
Copy paste the following content into the file editor (note that the leading whitespace is important for lines in this file since it communicates structure in yaml):
```
name: Foo Bar
description: Provides a baz for every contact's bat
category: extension

langs:
  en:
    repo: 'https://lab.civicrm.org/extensions/foobar'

searchterms:
  - provides baz
  - every contact's bat
  - bat
  - baz
  - contact
```
- There are lots of other settings you can put here if you want to have multiple languages or versions. Look at user.yml as an example of a guide (the User Guide) which takes advantage of all the possible settings.
- But if you want to keep it simple and just have one English edition which points to the master branch of your repo, then stick with the above settings.

Searching extension books.

Soon our docs-publisher will allow filtering/searching extension books this will be based on the values provided for 'tags' above.

Adjust name and repo to your own values
- The name you set here will be shown in the list of all guides on docs.civicrm.org as well as at the top of every page of your guide. Use whatever short name you've chosen for your extension, such as "Foo Bar", or "CiviFoobar". (Don't use a fully qualified name like "org.civicrm.foobar" because that wouldn't look so nice to visitors.)
For the commit message, write something like "Add new Foobar Guide".
Click Commit changes.
Click Merge requests > New merge request.
- Set the source branch to your fork and master.
- Set the target branch to the upstream repository and master.
- Click Compare branches and continue.
- Click Submit merge request.

At some point (hopefully soon!) someone will merge your MR and get the necessary config for your guide up on the server. Then it can be published.

Manually publish your guide¶

Once your guide's config is up, you can go to the following URL to ask the publishing system to publish (or re-publish) your guide:

https://docs.civicrm.org/admin/publish/foobar

(where foobar is the short name you used for your guide)

Publishing your guide manually is fine at first, but once you update the guide later, you might wish to avoid this extra step. This is why we have automatic publishing.

Set up automatic publishing¶

When you set up automatic publishing, GitLab or GitHub will tell the publishing system when content within your repo has changed, and the publishing system will re-publish your guide as necessary.

See the docs-publisher instructions for how to set up automatic publishing on GitHub and GitLab.

Now when you make changes to your docs, those changes will be published automatically and you'll receive an email notification from the publishing system informing you of the status (including any errors) of the publishing process.

Make your documentation discoverable¶

Hey, you're not done yet! Don't forget to to add links to your new guide in all the places where your users might look. This includes this following:

The listing for your extension in the civicrm.org extensions directory
Your README file

Your extension's info.xml file like this:

<urls>
    <url desc="Documentation">http://docs.civicrm.org/foobar/en/latest</url>
</urls>

Other places from within your extension's UI, as necessary.
Anywhere else that you previously had documentation (e.g. CiviCRM wiki, dedicated site, etc.)