mirror of
https://github.com/material-components/material-components-ios.git
synced 2026-01-15 01:02:22 +08:00
e1e6d249a4
As part of our readme generator, components can now opt in to displaying badges in their readme. The badges are generated from https://shields.io/ and are focused on an individual component. We're currently generating the following badges: - Open bug count.
116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
# Documentation
|
|
|
|
Every component is expected to provide complete API documentation for every public API and a
|
|
top-level README.md file that includes the following:
|
|
|
|
- A description of the component in relation to the Material spec.
|
|
- A looping, animated gif of the component.
|
|
- Links to Design and API documentation.
|
|
- A list of related components, if any.
|
|
- An overview that describes the primary APIs for the component.
|
|
- Installation steps.
|
|
- Usage guides. Must include at least one typical use article.
|
|
- Extensions articles, if any.
|
|
|
|
## Documentation conventions
|
|
|
|
```
|
|
components/
|
|
Component/
|
|
.vars <- A list of variables that can be used by the template generators.
|
|
README.md <- This is an auto-generated file. Do not modify it directly.
|
|
docs/ <- All documentation source lives here.
|
|
README.md <- The root index of your component's documentation.
|
|
article.md <- An article that is linked to from your root index.
|
|
assets/ <- All pngs, gifs live here.
|
|
```
|
|
|
|
## docs/README.md template
|
|
|
|
Use the following template command as a starting point for component documentation:
|
|
|
|
```bash
|
|
./scripts/apply_template ComponentName scripts/templates/component/docs/README.md.template components/ComponentName/docs/README.md
|
|
```
|
|
|
|
This will create a README.md in your component's `docs/` directory.
|
|
|
|
### .vars file
|
|
|
|
The `.vars` defines common template variables for a component. This file should be a list of
|
|
`variable_name=value` lines.
|
|
|
|
The list of possible variables are:
|
|
|
|
```markdown
|
|
component=
|
|
component_name=
|
|
a_component_name=
|
|
root_path=
|
|
icon_id=
|
|
short_description=
|
|
color_themer_api=
|
|
typography_themer_api=
|
|
themer_parameter_name=
|
|
guidelines_short_link=
|
|
guidelines_title=
|
|
```
|
|
|
|
If a variable is not provided and a template requires it, then the template will be generated with
|
|
the missing variables shown as placeholders still.
|
|
|
|
### Badges
|
|
|
|
To generate badges for a component, use the following snippet.
|
|
|
|
```markdown
|
|
<!-- badges -->
|
|
```
|
|
|
|
### Design & API links
|
|
|
|
To generate design and API links, use the following snippet. Note that this requires that you've
|
|
installed [jazzy](https://github.com/realm/jazzy).
|
|
|
|
```markdown
|
|
<!-- design-and-api -->
|
|
```
|
|
|
|
### Embedding articles
|
|
|
|
To embed an article in the generated readme, use the following syntax:
|
|
|
|
```markdown
|
|
- [Article title](article-file.md)
|
|
```
|
|
|
|
### Showing a table of contents
|
|
|
|
The following snippet will tell the readme generator to create a table of contents.
|
|
|
|
```markdown
|
|
<!-- toc -->
|
|
```
|
|
|
|
### Showing installation steps
|
|
|
|
Use the following snippet to generate installation docs for your component:
|
|
|
|
```markdown
|
|
## Installation
|
|
|
|
- [Typical installation](../../../docs/component-installation.md)
|
|
```
|
|
|
|
- - -
|
|
|
|
## Generating documentation
|
|
|
|
To generate the root README.md file for a given component, run:
|
|
|
|
```bash
|
|
./scripts/generate_readme ActivityIndicator
|
|
```
|
|
|
|
This will generate the root README.md from `docs/README.md` and any linked-to articles.
|