From 9a3cd8e26f4302507ac0877e37f1b7f48a716f14 Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Mon, 22 May 2023 13:31:30 +0200 Subject: [PATCH] DOCS: Documentation Style Guide (#2383) Co-authored-by: Tom Limoncelli --- documentation/SUMMARY.md | 3 +- documentation/adding-new-rtypes.md | 8 +- .../dnsconfig-code-example-with-filename.md | 10 + ...dnsconfig-code-example-without-filename.md | 10 + .../markdown-examples/hint/hint-danger.md | 3 + .../markdown-examples/hint/hint-info.md | 3 + .../markdown-examples/hint/hint-success.md | 3 + .../markdown-examples/hint/hint-warning.md | 3 + documentation/providers/hexonet.md | 2 +- documentation/release-engineering.md | 2 +- .../{styleguide.md => styleguide-code.md} | 0 documentation/styleguide-doc.md | 201 ++++++++++++++++++ documentation/writing-providers.md | 3 +- 13 files changed, 242 insertions(+), 9 deletions(-) create mode 100644 documentation/markdown-examples/code/dnsconfig-code-example-with-filename.md create mode 100644 documentation/markdown-examples/code/dnsconfig-code-example-without-filename.md create mode 100644 documentation/markdown-examples/hint/hint-danger.md create mode 100644 documentation/markdown-examples/hint/hint-info.md create mode 100644 documentation/markdown-examples/hint/hint-success.md create mode 100644 documentation/markdown-examples/hint/hint-warning.md rename documentation/{styleguide.md => styleguide-code.md} (100%) create mode 100644 documentation/styleguide-doc.md diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 8b6ab9867..c5562f21a 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -154,7 +154,8 @@ ## Developer info -* [Style Guide](styleguide.md) +* [Code Style Guide](styleguide-code.md) +* [Documentation Style Guide](styleguide-doc.md) * [DNSControl is an opinionated system](opinions.md) * [Writing new DNS providers](writing-providers.md) * [Creating new DNS Resource Types (rtypes)](adding-new-rtypes.md) diff --git a/documentation/adding-new-rtypes.md b/documentation/adding-new-rtypes.md index 4f68e9452..f63cf02cb 100644 --- a/documentation/adding-new-rtypes.md +++ b/documentation/adding-new-rtypes.md @@ -60,14 +60,14 @@ a minimum. - Run stringer to auto-update the file `dnscontrol/providers/capability_string.go` ```shell -pushd; cd providers; +pushd; cd providers/; stringer -type=Capability popd ``` alternatively ```shell -pushd; cd providers; +pushd; cd providers/; go generate popd ``` @@ -180,7 +180,7 @@ See also `017-txt.js`. Run these tests via: ```shell -cd dnscontrol/pkg/js +cd pkg/js/ go test ./... ``` @@ -252,7 +252,7 @@ in the source code. To run the integration test with the BIND provider: ```shell -cd dnscontrol/integrationTest +cd integrationTest/ go test -v -verbose -provider BIND ``` diff --git a/documentation/markdown-examples/code/dnsconfig-code-example-with-filename.md b/documentation/markdown-examples/code/dnsconfig-code-example-with-filename.md new file mode 100644 index 000000000..e20a1ed6b --- /dev/null +++ b/documentation/markdown-examples/code/dnsconfig-code-example-with-filename.md @@ -0,0 +1,10 @@ +{% code title="dnsconfig.js" %} +```javascript +var REG_NONE = NewRegistrar('none'); +var DNS_BIND = NewDnsProvider('bind'); + +D('example.com', REG_NONE, DnsProvider(DNS_BIND), + A('@', '1.2.3.4') +); +``` +{% endcode %} diff --git a/documentation/markdown-examples/code/dnsconfig-code-example-without-filename.md b/documentation/markdown-examples/code/dnsconfig-code-example-without-filename.md new file mode 100644 index 000000000..bab18a37b --- /dev/null +++ b/documentation/markdown-examples/code/dnsconfig-code-example-without-filename.md @@ -0,0 +1,10 @@ +{% code %} +```javascript +var REG_NONE = NewRegistrar('none'); +var DNS_BIND = NewDnsProvider('bind'); + +D('example.com', REG_NONE, DnsProvider(DNS_BIND), + A('@', '1.2.3.4') +); +``` +{% endcode %} diff --git a/documentation/markdown-examples/hint/hint-danger.md b/documentation/markdown-examples/hint/hint-danger.md new file mode 100644 index 000000000..ab4d056a9 --- /dev/null +++ b/documentation/markdown-examples/hint/hint-danger.md @@ -0,0 +1,3 @@ +{% hint style="danger" %} +**Danger hints** are good for highlighting destructive actions or raising attention to critical information. +{% endhint %} diff --git a/documentation/markdown-examples/hint/hint-info.md b/documentation/markdown-examples/hint/hint-info.md new file mode 100644 index 000000000..10dac9c7c --- /dev/null +++ b/documentation/markdown-examples/hint/hint-info.md @@ -0,0 +1,3 @@ +{% hint style="info" %} +**Info hints** are great for showing general information, or providing tips and tricks. +{% endhint %} diff --git a/documentation/markdown-examples/hint/hint-success.md b/documentation/markdown-examples/hint/hint-success.md new file mode 100644 index 000000000..360afbc8d --- /dev/null +++ b/documentation/markdown-examples/hint/hint-success.md @@ -0,0 +1,3 @@ +{% hint style="success" %} +**Success hints** are good for showing positive actions or achievements. +{% endhint %} diff --git a/documentation/markdown-examples/hint/hint-warning.md b/documentation/markdown-examples/hint/hint-warning.md new file mode 100644 index 000000000..f0b5d4f62 --- /dev/null +++ b/documentation/markdown-examples/hint/hint-warning.md @@ -0,0 +1,3 @@ +{% hint style="warning" %} +**Warning hints** are good for showing important information or non-critical warnings. +{% endhint %} diff --git a/documentation/providers/hexonet.md b/documentation/providers/hexonet.md index a2cb414de..36653dc09 100644 --- a/documentation/providers/hexonet.md +++ b/documentation/providers/hexonet.md @@ -57,7 +57,7 @@ dnscontrol get-zones --format=nameonly hexonet HEXONET all ``` ```shell # Review the output. Pick one domain and set HEXONET_DOMAIN. -cd $GIT/dnscontrol/integrationTest +cd integrationTest/ export HEXONET_DOMAIN=yodream.com # Pick a domain name. export HEXONET_ENTITY=OTE export HEXONET_UID=test.user diff --git a/documentation/release-engineering.md b/documentation/release-engineering.md index dd4b6caf6..869911ec2 100644 --- a/documentation/release-engineering.md +++ b/documentation/release-engineering.md @@ -235,7 +235,7 @@ Build the software: {% endhint %} ```shell -cd docs/flattener +cd docs/flattener/ export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)" export GOOS=linux gopherjs build diff --git a/documentation/styleguide.md b/documentation/styleguide-code.md similarity index 100% rename from documentation/styleguide.md rename to documentation/styleguide-code.md diff --git a/documentation/styleguide-doc.md b/documentation/styleguide-doc.md new file mode 100644 index 000000000..4d6178eb7 --- /dev/null +++ b/documentation/styleguide-doc.md @@ -0,0 +1,201 @@ +# Documentation Coding Style + +## Where are the docs? + +TL;DR version: [`docs`](https://github.com/StackExchange/dnscontrol/tree/master/docs) is the [marketing website](https://dnscontrol.org). [`documentation`](https://github.com/StackExchange/dnscontrol/tree/master/documentation) is the [docs.dnscontrol.org](https://docs.dnscontrol.org/) website. (Yes, the names are backwards!) + +**The two websites** + +1. + * The main website + * Source code: [`docs`](https://github.com/StackExchange/dnscontrol/tree/master/docs) + * Mostly "marketing" for the project. + * Rarely changes. Updated via GitHub "pages" feature. +2. + * Project documentation + * Source code: [`documentation`](https://github.com/StackExchange/dnscontrol/tree/master/documentation) + * Users and developer documentation + * Changes frequently. Updated via [GitBook](https://www.gitbook.com/) + +**The directory structure** + +Within the git repo, docs are grouped: + +* [`documentation/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation): general docs +* [`documentation/providers/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/providers/): One file per provider +* [`documentation/functions/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/functions/): One file per `dnsconfig.js` language feature +* [`documentation/assets/FOO/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/assets/): Images for page FOO(PNGs only, please!) + +## How to add a new page? + +1. Add the page to the `documentation` folder (possibly a sub folder) +2. List the page in `SUMMARY.md` so that it will appear in the table of contents, sidebar, etc. + +## Documentation previews + +> "Preview links are only accessible by GitBook users. We're working on a feature that will allow preview links to be viewable by anyone who accesses the PR." — _[GitBook](https://docs.gitbook.com/product-tour/git-sync/github-pull-request-preview#how-to-access-preview-links)_ + +## Formatting tips + +### General + +Break lines every 80 chars. + +Include a blank line between paragraphs. + +Leave one blank line before and after a heading. + +Javascript code should use double quotes (`"`) for strings, not single quotes +(`'`). They are equivalent but consistency is good. + +### Headings + +```markdown +# Title of the page + +## Heading + +At least one paragraph. + +## Subheadings + +At least one paragraph. + +* **Step 1: Foo** + +Description of the step. + +* **Step 2: Bar** + +Description of the step. + +(further sub sub headings are discouraged encouraged) +``` + +### Code Snippets + +See the examples below, for the Markdown syntax click on the 'Source code'. + +Long example: (with filename) + +{% code title="dnsconfig.js" %} +```javascript +var REG_NONE = NewRegistrar('none'); +var DNS_BIND = NewDnsProvider('bind'); + +D('example.com', REG_NONE, DnsProvider(DNS_BIND), + A('@', '1.2.3.4') +); +``` +{% endcode %} + +[Source code](markdown-examples/code/dnsconfig-code-example-with-filename.md?plain=1) + +Long example: (without filename) + +{% code %} +```javascript +var REG_NONE = NewRegistrar('none'); +var DNS_BIND = NewDnsProvider('bind'); + +D('example.com', REG_NONE, DnsProvider(DNS_BIND), + A('@', '1.2.3.4') +); +``` +{% endcode %} + +[Source code](markdown-examples/code/dnsconfig-code-example-without-filename.md?plain=1) + +### Hint + +Hints are a great way to bring the reader's attention to specific elements in your documentation. + +There are 4 different types of hints, and both inline content and formatting are supported. + +### Example of a hint + +{% hint style="info" %} +**Info hints** are great for showing general information, or providing tips and tricks. +{% endhint %} + + [Source code](markdown-examples/hint/hint-info.md?plain=1) + +{% hint style="success" %} +**Success hints** are good for showing positive actions or achievements. +{% endhint %} + + [Source code](markdown-examples/hint/hint-success.md?plain=1) + +{% hint style="warning" %} +**Warning hints** are good for showing important information or non-critical warnings. +{% endhint %} + + [Source code](markdown-examples/hint/hint-warning.md?plain=1) + +{% hint style="danger" %} +**Danger hints** are good for highlighting destructive actions or raising attention to critical information. +{% endhint %} + + [Source code](markdown-examples/hint/hint-danger.md?plain=1) + +{% hint style="info" %} +### This is a heading + +This is a line + +This is a second line +{% endhint %} + +### Technical references + +#### Mentioning language features + +Not every mention to A, CNAME, or function +needs to be a link to the manual for that record type. +However, the first mention on a page should always +be a link. Others are at the authors digression. + +```markdown +The [`PTR`](functions/domain/PTR.md) feature is helpful in LANs. +``` + +#### Mentioning functions from the Source code + +```markdown +The function `GetRegistrarCorrections()` returns... +``` + +### Links + +#### Internal links + +```markdown +Blah blah blah [M365_BUILDER](functions/record/M365_BUILDER.md) +``` + +{% hint style="info" %} +**NOTE**: The `.md` is required. +{% endhint %} + +#### Link to another website + +Just list the URL. + +```markdown +Blah blah blah blah blah. +``` + +#### Link with anchor text + +```markdown +Blah blah blah [a search engine](https://www.google.com) blah blah. +``` + +## Proofreading + +Please spellcheck documents before submitting a PR. + +Don't be surprised if Tom rewrites your text. He often does that to keep the +documentation consistent and make it more approachable by new users. It's not +[because he has a big ego](https://www.amazon.com/stores/author/B004J0QIVM). +Well, not usually. diff --git a/documentation/writing-providers.md b/documentation/writing-providers.md index a17429677..4580cbddc 100644 --- a/documentation/writing-providers.md +++ b/documentation/writing-providers.md @@ -168,7 +168,6 @@ complex algorithms in the new code. Run the unit tests with this command: - cd dnscontrol go test ./... @@ -182,7 +181,7 @@ Integration tests use a test account and a real domain. For example, this will run the tests using BIND: ```shell -cd dnscontrol/integrationTest +cd integrationTest/ go test -v -verbose -provider BIND ```