Skip to content
This repository has been archived by the owner on Sep 22, 2023. It is now read-only.

Commit

Permalink
Merge pull request #4 from Amplitude-Developer-Docs/apidocconvert
Browse files Browse the repository at this point in the history
Branch got unwieldy and I needed to move on.
caseyamp authored Mar 10, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
2 parents f8f1b60 + 5cf23d2 commit 6a3bf8a
Showing 49 changed files with 5,892 additions and 368 deletions.
25 changes: 24 additions & 1 deletion .github/workflows/link-check-config.json
Original file line number Diff line number Diff line change
@@ -4,8 +4,31 @@
"pattern": "^https://developer.android.com/reference/android/Manifest.permission"
},
{
"pattern": "https://help.amplitude.com/hc/en-us/articles/"
"pattern": "https://help.amplitude.com/hc"
},
{
"pattern": "^https://api2.amplitude"
},
{
"pattern": "^https://api.eu"
},

{
"pattern": "^https://amplitude.com/api"
},

{
"pattern": "^https://analytics.eu.amplitude.com/api"
},

{
"pattern": "assets/images/"
},

{
"pattern": "https://core.amplitude.com/scim/1/"
}

]

}
237 changes: 237 additions & 0 deletions .markdownlint.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,237 @@
# markdownlint YAML configuration for the Amplitude Dev Center project

# Path to configuration file to extend
extends: null

# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
MD001: true

# We don't use this rule because the title metadata becomes the first #h1
# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
# MD002:
# Heading level
#level: 1

# MD003/heading-style/header-style - Heading style
MD003:
# Heading style
style: "consistent"

# MD004/ul-style - Unordered list style
MD004:
# List style
style: "consistent"

# MD005/list-indent - Inconsistent indentation for list items at the same level
MD005: true

# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
MD006: true

# MD007/ul-indent - Unordered list indentation
MD007:
# Spaces for indent
indent: 2
# Whether to indent the first level of the list
start_indented: false
# Spaces for first level indent (when start_indented is set)
start_indent: 2

# MD009/no-trailing-spaces - Trailing spaces
MD009:
# Spaces for line break
br_spaces: 2
# Allow spaces for empty lines in list items
list_item_empty_lines: false
# Include unnecessary breaks
strict: false

# MD010/no-hard-tabs - Hard tabs
MD010:
# Include code blocks
code_blocks: true
# Number of spaces for each hard tab
spaces_per_tab: 1

# MD011/no-reversed-links - Reversed link syntax
MD011: true

# MD012/no-multiple-blanks - Multiple consecutive blank lines
MD012:
# Consecutive blank lines
maximum: 1

# MD013/line-length - Line length
MD013:
# Number of characters
line_length: 200
# Number of characters for headings
heading_line_length: 80
# Number of characters for code blocks
code_block_line_length: 80
# Include code blocks
code_blocks: false
# Include tables
tables: false
# Include headings
headings: true
# Include headings
headers: true
# Strict length checking
strict: false
# Stern length checking
stern: false

# MD014/commands-show-output - Dollar signs used before commands without showing output
MD014: true

# MD018/no-missing-space-atx - No space after hash on atx style heading
MD018: true

# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
MD019: true

# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
MD020: true

# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
MD021: true

# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
MD022:
# Blank lines above heading
lines_above: 1
# Blank lines below heading
lines_below: 1

# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
MD023: true

# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
MD024:
# Only check sibling headings
allow_different_nesting: false
# Only check sibling headings
siblings_only: true

# MD025/single-title/single-h1 - Multiple top-level headings in the same document
MD025:
# Heading level
level: 1
# RegExp for matching title in front matter
front_matter_title: "^\\s*title\\s*[:=]"

# MD026/no-trailing-punctuation - Trailing punctuation in heading
MD026:
# Punctuation characters
punctuation: ".,;:!。,;:!"

# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
MD027: true

# MD028/no-blanks-blockquote - Blank line inside blockquote
MD028: true

# MD029/ol-prefix - Ordered list item prefix
MD029:
# List style
style: "one_or_ordered"

# MD030/list-marker-space - Spaces after list markers
MD030:
# Spaces for single-line unordered list items
ul_single: 1
# Spaces for single-line ordered list items
ol_single: 1
# Spaces for multi-line unordered list items
ul_multi: 1
# Spaces for multi-line ordered list items
ol_multi: 1

# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
MD031:
# Include list items
list_items: true

# MD032/blanks-around-lists - Lists should be surrounded by blank lines
MD032: true

# MD033/no-inline-html - Inline HTML
MD033:
# Allowed elements
allowed_elements: [div, br]

# MD034/no-bare-urls - Bare URL used
MD034: true

# MD035/hr-style - Horizontal rule style
MD035:
# Horizontal rule style
style: "consistent"

# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
MD036:
# Punctuation characters
punctuation: ".,;:!?。,;:!?"

# MD037/no-space-in-emphasis - Spaces inside emphasis markers
MD037: true

# MD038/no-space-in-code - Spaces inside code span elements. Not in use because of Material's admonition syntax
MD038: false

# MD039/no-space-in-links - Spaces inside link text
MD039: true

# MD040/fenced-code-language - Fenced code blocks should have a language specified
MD040: true

# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
MD041:
# Heading level
level: 1
# RegExp for matching title in front matter
front_matter_title: "^\\s*title\\s*[:=]"

# MD042/no-empty-links - No empty links
MD042: true

# MD043/required-headings/required-headers - Required heading structure
MD043: false
# List of headings
# headings: []
# List of headings
# headers: []

# MD044/proper-names - Proper names should have the correct capitalization
MD044:
# List of proper names
names: []
# Include code blocks
code_blocks: true

# MD045/no-alt-text - Images should have alternate text (alt text)
MD045: true

# MD046/code-block-style - Code block style Not in use because it gets confused by the tabs and admonition syntax.
MD046: false
# Block style
#style: "fenced"

# MD047/single-trailing-newline - Files should end with a single newline character
MD047: true

# MD048/code-fence-style - Code fence style
MD048:
# Code fence style
style: "consistent"

# MD049/emphasis-style - Emphasis style should be consistent
MD049:
# Emphasis style should be consistent
style: "consistent"

# MD050/strong-style - Strong style should be consistent
MD050:
# Strong style should be consistent
style: "consistent"
8 changes: 8 additions & 0 deletions .vale.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
StylesPath = "vale/styles"

MinAlertLevel = suggestion

Vocab = dev

[*.md]
BasedOnStyles = Vale, Amplitude, write-good, Readability
23 changes: 15 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# README

**THIS IS A WIP. PING CASEY SMITH FOR HELP
**THIS IS A WORK IN PROGRESS. PING CASEY SMITH FOR HELP
**

This is the Amplitude Developer Center site.
@@ -9,7 +9,7 @@ To get started with contributing, first read PLACEHOLDER FOR DOCS ONCE I WRITE T

## Install

Before you get started, you need pip installed. To install the the link checker and Vale locally, you'll need to have brew and npm too.
Before you get started, you need pip. To install the link checker and Vale locally, you'll need brew and npm too.

### 1. Install Material

@@ -25,7 +25,7 @@ Most dependencies are installed with this command.

`npm install -g markdown-link-check`

We have a GitHub Action that runs a link checker for PRs, but it's annoying to only find out links are broken after you open your PR. If you install the link checker, you can run the linter locally with this command: `markdown-link-check -c .github/workflows/link-check-config.json path/to/your/file.md`. It's not perfect, so if you find that the job repeatedly fails on a valid link, then add the pattern to ignore to the config.json file.
We use a GitHub Action that runs a link checker for PRs, but it's annoying to only find out links are broken after you open your PR. If you install the link checker, run the linter locally with this command: `markdown-link-check -c .github/workflows/link-check-config.json path/to/your/file.md`. It's not perfect, so if you find that the job repeatedly fails on a valid link, then add the pattern to ignore to the `.github/workflows/link-check-config.json` file.

### 4. (Optional, but highly encouraged) Install Vale CLI

@@ -38,6 +38,8 @@ Most dependencies are installed with this command.
- [VS Code](https://github.com/errata-ai/vale-vscode)
- [Vim](https://github.com/dense-analysis/ale)
- [Sublime](https://github.com/errata-ai/SubVale)

The changes Vale flags are mostly suggestions, but please make an effort to address problems. The closer we stick to the style guide, the better our docs will be.

### 5. Clone this Repo

@@ -46,22 +48,27 @@ Most dependencies are installed with this command.
Preview changes locally using `mkdocs serve`

When you're ready, open a PR against [PLACEHOLDER FOR STAGING BRANCH], and tag your reviewer. Opening a PR against [PLACEHOLDER FOR STAGING BRANCH] creates a preview site where you can check your changes.



### 7. Merge

After your PR is approved, merge it.
After your PR is approved, merge it. Merging to main publishes to the website.


## Notes
- The files in the repo make use of [Insiders](https://squidfunk.github.io/mkdocs-material/insiders/) features. If you don't have Insiders, you can still build, but some [features](https://squidfunk.github.io/mkdocs-material/insiders/#available-features) won't render in your build.
- If you're using VS Code, install the [markdownlint extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). This extension flags problems with your markdown. The project includes a config file to cut down on noisier errors.
- If you're using VS Code, install the [markdownlint extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). This extension flags problems with your markdown. The project includes a config file to cut down on noisier errors.

## Resources

## Resources
[Material Docs](https://squidfunk.github.io/mkdocs-material/)

[Markdown Link Check](https://github.com/tcort/markdown-link-check)

[Vale Docs](https://docs.errata.ai/)

## Known issues and hacks I don't feel bad about

- **Two mkdocs config files**. Because of the way Insiders and config inheritance works, I had to make a config file for people who don't have Insiders and one for the build bot (which does have Insiders). This was intentional. Site builds should always use `insiders.mkdocs.yml`. If you want to know more, read the dissertation I wrote in `insiders.mkdocs.yml`.
- **Column CSS classes**. Markdown tables are easier to write than HTML tables. However, column width is set by the width of the contents in the first cell for each column. This can lead to too-narrow column widths in some data tables (especially param tables). Because you can add HTML to markdown, I created some CSS classes to manually set the width in cases where it makes sense. Just wrap the contents of the column's table heading with a `<div class="big-column">`. See `docs/stylesheets/extra.css` and search for "column width classes" for an explanation and the classes.
- **Unsupported language syntax highlighting**. The project uses Pygments for code syntax highlighting. As with all highlighters, some languages aren't explicitly supported. If you can't find your language supported in [this list](https://pygments.org/languages/), you can either write your own, or just use the closest thing you can. This is an edge case. For NodeJs, just use `js`.

Loading

0 comments on commit 6a3bf8a

Please sign in to comment.