TL;DR - This PR consists of fixes for broken links, broken image links, and broken Swift/Objective-C code snippets on material.io, and also adds some small copy edits.
Sometimes our documentation renders okay on GitHub, but breaks in the conversion of markdown to HTML/CSS that takes place during material.io deploys. As of yesterday, I'm able to build material.io locally, which allows me _validate_ the documentation changes I will keep making for the material.io work. It also allows me to catch broken links elsewhere, in totally unrelated files. For example, there were broken links in some Shapes documentation that were already blocking the deployment of our docs unbeknownst to us.
Closes https://github.com/material-components/material-components-ios/pull/9963
COPYBARA_INTEGRATE_REVIEW=https://github.com/material-components/material-components-ios/pull/9963 from andrewoverton:fix-formatting-issues cd54e90863274a49068e016547b1bf0b1af3afcb
PiperOrigin-RevId: 305770167
Closes https://github.com/material-components/material-components-ios/issues/7108
This change adds a migration guide for moving from Themers to Theming Extensions. Part of this migration guide requires that the reader knows which Theming extensions replace which Themer API, so the relevant APIs are being annotated accordingly as part of https://github.com/material-components/material-components-ios/issues/7108.
I considered making a table in the documentation with the API mappings, but realized quite quickly that this table would get out of date and be difficult to maintain, so the information is now present in each to-be-deprecated API's documentation instead.
While annotating the APIs I captured the ones that were missing theming extensions in https://github.com/material-components/material-components-ios/issues/7172. This issue can be used as an epic to track the remaining components that require theming extensions.
Refactor theming document with improved header for Themers and better section ordering with import dependencies -> how to use them -> examples.
Improves 5c14dca53a (#7210).
This PR will help clients who are using our library what to import if they are using our theming extensions. This also cleans up the ObjectiveC code to use more modern ObjC style.
We are currently stuck on Xcode 10.0 (possibly 10.1) and use CocoaPods 1.6.1. We no longer support CocoaPods 1.5.x, nor do we regularly use Xcode 9.x except for presubmit testing.
Fixes#7143
This discourages depending on all of a component's extensions and aligns our targets more closely with how we expect them to be imported and depended upon.
This is a breaking change.
Pivotal story: https://www.pivotaltracker.com/story/show/157118721
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">
* Updated known shortlink destination URLs to use short links.
* Updated stray links in the CHANGELOG.md.
* Fixed FAB shortlink.
* Applied replacements to everything outside of components/.
* [Docs] Changes an icon list class name.
* [Docs] Adds annotations to all installation code snippets.
* [Docs] Fixes screenshot sizes in PageControl README.
* [Docs] Fixes a broken link on the homepage.
* [Docs] Adds a stable repository branch field to the site metadata.
Used to link to the GitHub source tree.
* [Docs] Specify platform in docs root title.
* [Docs] Adds platform configuration for the doc site.
* [Docs] Adds path metadata for documentation site.
This field is used to determine where the file will appear in the
doc site.
* [Docs] Updates Material guideline links to latest URL.
material.google.com -> material.io/guidelines
* [Docs] Introduces a separate component index for the docsite.
* [Docs] Changes the directory used for site generation.
* [Docs] Moves documentation-site-only Markdown into its own directory.
* [Docs] Changes material.io links to use https.
* [Docs] Renames the howto and contributing docsite sections to docs.
* [Docs] Adds a navTitle field to the collection editing/styling pages.
* [Docs] Changes the FAQ heading to be one size bigger.
* [Docs] Changes the tutorial title.
* [Docs] Adds icons to three more components.
* [Docs] Introduces a root component directory called /catalog/.
* [Docs] Adds an icon to the AnimationTiming component.
* [Docs] Adds an icon for the typography component.
* [Docs] Reformats the docsite index.
