Skip to content

Latest commit

 

History

History
63 lines (47 loc) · 2.51 KB

CONTRIBUTING.md

File metadata and controls

63 lines (47 loc) · 2.51 KB
Raw

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owner of this repository before making a change. The best way to contribute a change is through a pull request.

If you want to add an additional feature, first consider if the feature could be made available through an add-on package. If the feature turns out to be universally useful, it can be incorporated later into the core code.

How to modify and test the core docassemble code

For instructions on how to test modificiations to the core code, see the workflow for making changes to the core docassemble code.

How to contribute to the documentation

The documentation is written in GitHub Pages. It is available in the gh-pages branch of the GitHub repository.

How to write a code example

Code examples appear in the documentation and in the "examples" area of the Playground. These come from interview YAML files that are stored in docassemble_base/docassemble/base/data/questions/examples.

There is a script that automatically generates screenshots for the code samples and carries over the YAML text into the documentation. So if you want to contribute a code example, just add a YAML file to docassemble_base/docassemble/base/data/questions/examples.

Each interview should begin with a metadata block like the following:

metadata:
  title: Test if user is logged in
  short title: Logged in
  documentation: "https://docassemble.org/docs/functions.html#user_logged_in"
  example start: 2
  example end: 5

The documentation should be a link to the documentation. You can see in the "examples" area of the Playground that each code example has a link to the documentation; this is where that link comes from.

Most code examples are displayed as excerpts from the full interview example. The example start and example end metadata tags identify the start and end blocks. Note that the numbers start at zero, so the first block in the YAML file (which is usually the metadata block) is block 0.

If you want your code example to appear in the "examples" area of the Playground, edit the docassemble_base/docassemble/base/data/questions/example-list.yml file and add a reference to your YAML file.

To add a code example to a page of the documentation, include a line like the following:

{% include side-by-side.html demo="user-logged-in" %}