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

Apidocconvert #4

Merged
merged 39 commits into from
Mar 10, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
2238361
Building out Attribution API
Feb 25, 2022
c668431
Pulling in changes so I don't step on myself:
Feb 25, 2022
9833fbb
Updating Link Check config to exclude API endpoints
Feb 25, 2022
bf266bc
Adding Batch Event Upload doc and making small tweaks to other stuff
Feb 25, 2022
02787bf
checking in Behavioral Cohorts api doc for the weekend
Feb 25, 2022
57d4a25
Finished draft of behavioral cohorts api
Feb 28, 2022
4657cb8
making minor fix to attr api doc
Feb 28, 2022
d752a5e
adding chart annotations
Feb 28, 2022
ae44f2f
fixing broken code block
Feb 28, 2022
2a2e469
CCPA DSAR and other updates
Feb 28, 2022
446236a
adding new files, adding vale as a submodule
Mar 1, 2022
56dd65e
added dashboard-rest-api rough draft
Mar 1, 2022
0735c00
updated vale submodule
Mar 1, 2022
9b8b177
polishing up dashboard rest API doc and updating link check rules
Mar 2, 2022
c19b243
messing with vale and also export-api
Mar 2, 2022
7e41b4d
adding group identify api
Mar 2, 2022
b2ca0d7
standardizing file names for the reusables
Mar 2, 2022
ae7ebb4
adding identify API
Mar 3, 2022
6f2f0bc
added releases API doc
Mar 3, 2022
8b57443
typo fix
Mar 3, 2022
d996a7d
adding SCIM doc, plus configured the markdownlint file for the project
Mar 3, 2022
bcba324
Pulling readme updates in so I don't have to switch branches when I t…
Mar 3, 2022
0183ef1
tine updates
Mar 3, 2022
8ff7c86
adding shell for taxonomy API + getting metadocs together
Mar 3, 2022
d96a7d5
little fixes
Mar 4, 2022
7c85ba9
Adding analytics overview and moving some things around
Mar 4, 2022
c0454c8
Adding doain proxy guide
Mar 4, 2022
9e6bb7d
fixing link checker and chaning some text
Mar 4, 2022
1274133
added first draft of http-v2-api
Mar 4, 2022
07dbb5c
adding accessibestuff
Mar 7, 2022
5dfa34b
fixing vale
Mar 7, 2022
b57dd3f
still trying to fix vale
Mar 7, 2022
9089168
Fixing vale again
Mar 7, 2022
02af8b6
fixing broken links
Mar 7, 2022
ebb788c
wrapping up draft of Http v2 doc
Mar 7, 2022
e95dc54
Adding user privacy API doc and tweaking linter rules
Mar 8, 2022
e29d658
updating taxonomy API, a few vale changes
Mar 9, 2022
394ee66
updated according to Izaaz comments
Mar 9, 2022
5cf23d2
Merge branch 'main' into apidocconvert
caseyamp Mar 10, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion .github/workflows/link-check-config.json
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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