Skip to main content

Documentation updates

This documentation is our main channel of communication and the only source of truth for all material about the project. Helping with the evolution of documentation is just as important as the evolution of the code itself.

There are a few ways to help:

Topics about special parts of documentation:

  • Components API: the API documentation of the components is auto-generated by a script using a template.

Creating new or update a content​

First of all, you need to know about Git, and the basics of GitHub, in order to work with Tangram. You have two paths:

  • I don't know and I don't want to learn Git. In this case, create an issue here and ask one of the maintainers to create or update the page in question.
  • I know, or I can handle it. Excellent! Then follow the step by step below.

Setting up the environment​

If you're not used to working with Git and GitHub, you can use HackMD which is a markdown editor that already has GitHub integration, so you can use it right from your browser without having to install anything on your machine.

Otherwise, with Git already installed, you can clone the project:

git clone git@github.com:ResultadosDigitais/tangram.git

New branch​

Create a new branch so you can safely make your changes and then submit them for review. Through the terminal it can be done through the command:

cd tangram
git checkout -b my-new-branch

Change the my-new-branch with the name of your branch. The branch name are words separated by hyphens, usually is a short description of what the change is about, for example: add-testing-guide, translate-drawer-doc.

Writing​

The documentation is divided into 3 directories: docs/code, docs/docs and docs/examples and each of these directories has a responsibility.

If you need to create documentation for a component, the files must be created in the directories docs/docs (with text about the component usage) and docs/examples (with the component usage examples).

If you want to add a more generic page, which is part of the other categories of documentation, you should create it inside the docs/docs directory, in the corresponding folder.

The docs/code directory does not need to be changed as the files contained therein are generated automatically.

Text must be written in both English and Portuguese, access the topic Translating for more details on how to update the translation.

All headers must have explicit ids to keep the link between all translations. You can create them manually, or you can leave without and at the end use the following script to generate them automatically:

yarn docs write-heading-ids

Create a pull request​

With all the changes made, now is the time to create a PR for Tangram maintainers to review.

If you haven't committed your changes yet, then do it with the command:

git add file1 file2
git commit -m "docs: description about the changes"

Read about our commit message pattern here.

Then push your changes to GitHub:

git push -u origin my-new-branch

Change the my-new-branch with the brach you just created. The command output will give you a URL to create the Pull Request, click on it to do that.

With the page open to create the Pull request, add the version label. Since you are changing the documentation, choose the label tag: documentation.

The title will be filled in the same as you defined when creating the branch. If it's written well, it doesn't need to change.

In the description is where you go into the detail of the change to give context for reviewers. Tangram already has a template, so just read and follow the guidelines.

Finally, just click the "Create pull request" button to create it. Then wait for one of the project maintainers to review your request and interact with you on the Pull request itself.

Translating​

Although Docusaurus provides native support for internationalization, our translation process is still quite manual.

First, confirm that all headers has explicit id:

yarn docs write-heading-ids

Explicit ids will ensure that the link to titles are the same between translations.

Then run the script to write the translation keys not yet done:

yarn docs write-translations

Now just access the translation files in the docs/i18n/pt-BR directory and follow the same directory structure pattern as mentioned in one of the topics above.

To start your localized site in dev mode:

yarn docs start:br
tip

Each language is a unique and independent application, that is, it is not possible to start Docusaurus in all languages at the same time.

Generating documentation for components and hooks API​

Components and hooks API documentation is automatically generated using the following commands:

yarn docs write-components-api
yarn docs write-hooks-api
info

The scripts has to be run every time you need to update the documentation. But you can run it while Docusaurus is running and it will recognize the new changes with hot reload.

API documentation will only be generated for the components and hooks listed in the file docs/sidebars/sidebars.js. For the componentes in the COMPONENTS_CATEGORY array, and for the hooks in the HOOKS_CATEGORY.

In the case of the components, the array item must include the tab id "api". Example:

docs/sidebars/sidebars.js
const COMPONENTS_CATEGORY = [
  {
    label: 'Component1',
    // The "docs" must to be in docs/docs/components/component1.md
    path: 'components/component1',
    tabs: ['docs', 'api']
  },
  {
    label: 'Component2',
    // The "docs" must to be in docs/docs/components/component2.md
    path: 'components/component2',
    tabs: ['docs']
  }
];

In the example above, the script will try to generate the API documentation only for Component1, since it was the only one indicated that it will have the "api" tab.

This component must to be in the directory packages/components/src/component1/ (logic extract form path property), and the documentation will be generated in the docs/code/components/component1.md file.

All information for generation the documentation is taken from the comments of the component or hook itself. The comment must follow the JSDoc standard, this way the documentation is done only once and is reused for:

  • the code itself, facilitates code maintenance and evolution
  • it is exported in the lib contract, using Tangram as a lib it is possible to use the documentation directly from the code editor
  • used in this documentation

Block tags​

danger

The script does not delete an already created markdown file, you need to manually delete the file if that is the case.

The script recognizes the following Block Tags:

@ignore​

You can ignore a property so that it doesn't appear in the documentation:

MyComponent.propTypes = {
  /**
   * @ignore
   * Sets the children
   */
  children: PropTypes.node
};

Or you can ignore the entire component:

/**
 * @ignore
 */
function MyComponent() {}

@deprecated​

You can report that a particular property is depreciated:

MyComponent.propTypes = {
  /**
   * @deprecated since version 2
   * Sets the icon on the left side of the text
   */
  icon: PropTypes.node
};

The tag description is optional.

@param and @returns​

For the case of a property that is a function, it is possible to use tags @param and @returns, check out their documentation to learn how to define their syntax.

@example​

You can include additional examples with @example to illustrate the use of the property:

MyComponent.propTypes = {
  /**
   * Sets all options displayed by the menu.
   * @example
   * const options = [{value: 1, label: 'Joel'}, {value: 2, label: 'Ellie'}]
   * */
  options: PropTypes.arrayOf(PropTypes.shape({}))
};

The example will be displayed inside a code block using the JSX language for the synthax highlighting.

@since​

When adding a new property, be sure to specify which version from using the @since tag:

MyComponent.propTypes = {
  /**
   * Sets all options displayed by the menu.
   * @since 1.0.1
   * */
  options: PropTypes.arrayOf(PropTypes.shape({}))
};

Feedback​