mirror of
https://github.com/material-components/material-components-ios.git
synced 2026-01-09 07:11:20 +08:00
18617943ab
This PR adds a new script, `scripts/generate_readme`, which will generate a root README.md file for a component from the component's docs/ content.
The advantages of this script over our current process of writing readmes:
- Documentation articles can be broken out into separate files, making it easier to generate and apply templates.
- Our component readmes now have auto-generated table of contents.
- Our documentation can be written in plain markdown with minimal material.io html magic.
- Having docs in separate files doesn't result in multiple "component pages" on material.io - everything ends up in a single component document on the site. E.g. the "Color Theming" article no longer shows up as its own link on material.io.
Example usage:
```bash
./scripts/generate_readme ActivityIndicator
```
---
The script makes the following assumptions:
A component has the following directory structure:
```
components/
Component/
README.md <- The component's main readme.
This is the readme that will show up on material.io.
docs/
README.md <- A skeletal readme with links to other docs files.
some-article.md <- An article that may be linked to.
```
`components/Component/docs/README.md` is treated as a standard markdown file, with the additional interpretations:
```
* [Text](url)
Treated as an icon list for the material.io website.
If the url links to any go/design- url, the link will use the spec icon
- [Text](some-article.md)
Indicates that the linked article should be added verbatim to the main README.md
<!-- toc -->
A table of contents should be generated here.
```
The script then does the following:
1. Generates a template README from the component's .vars file.
2. Appends the component's docs/README.md to the readme.
3. Rewrites any asset and relative url paths.
4. Transforms all `* [text](link)`-formatted link lists into icon-list lists.
4b. If an icon list url points to a design site, the spec icon will be used for the list item.
5. Replaces every `- [text](link)`-formatted link list item with the contents of the file.
6. Generates a table of contents if `<!-- toc -->` is found. The table of contents will include all level 2 and 3 headers found after the toc tag.
7. Copies the output to the component's root README.md.
The implication of this script is that we can now write documentation as small files which are easier to templatize. These smaller files can be aggregated together into a single larger README.md that is consumable by the material.io website.
Example of table of contents on material.io:
<img width="460" alt="screen shot 2018-05-01 at 9 07 31 am" src="https://user-images.githubusercontent.com/45670/39473887-1fa6c85c-4d1f-11e8-8620-d6b151a315c6.png">
67 lines
2.0 KiB
Bash
Executable File
67 lines
2.0 KiB
Bash
Executable File
#!/bin/bash -e
|
|
#
|
|
# Copyright 2018-present The Material Components for iOS Authors. All Rights Reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
usage() {
|
|
echo "Usage: $0 <ComponentName> <path_to_.template_file> <destination>"
|
|
echo
|
|
echo "Copies the template into the component directory and replaces all of the symbols defined"
|
|
echo "in the component's .vars file."
|
|
echo
|
|
echo ".vars files should be placed in the root of the component's directory."
|
|
echo "Example: components/ActivityIndicator/.vars"
|
|
echo
|
|
echo "Each line of the .vars file should be of the form symbol=replacement."
|
|
echo "Example:"
|
|
echo "component=ActivityIndicator"
|
|
echo "component_name=Activity Indicator"
|
|
echo
|
|
echo "This script will replace all instances of <#symbol#> in the .template with the given"
|
|
echo "replacement."
|
|
echo
|
|
echo "Example usage: $0 scripts/templates/component/docs/color-theming.md.template components/ActivityIndicator/docs/color-theming.md"
|
|
}
|
|
|
|
if [ "$#" -ne 3 ]; then
|
|
usage
|
|
exit 1
|
|
fi
|
|
|
|
COMPONENT="$1"
|
|
TEMPLATE_PATH="$2"
|
|
DESTINATION_PATH="$3"
|
|
|
|
if [ ! -f "$TEMPLATE_PATH" ]; then
|
|
echo "$TEMPLATE_PATH is not a file."
|
|
echo
|
|
usage
|
|
exit 1
|
|
fi
|
|
|
|
mkdir -p $(dirname "$DESTINATION_PATH")
|
|
|
|
COMPONENT_VARS="components/$COMPONENT/.vars"
|
|
|
|
cp "$TEMPLATE_PATH" "$DESTINATION_PATH"
|
|
|
|
cat $COMPONENT_VARS | grep -v "^#" | while read line; do
|
|
variable=$(echo "$line" | cut -d'=' -f1)
|
|
replacement=$(echo "$line" | cut -d'=' -f2-)
|
|
|
|
echo "Replacing <#$variable#> with $replacement..."
|
|
|
|
perl -pi -e "s|<#$variable#>|$replacement|g" "$DESTINATION_PATH"
|
|
done
|