mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
DOCS: Documentation Style Guide (#2383)
Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
This commit is contained in:
committed by
GitHub
parent
cfcc451089
commit
9a3cd8e26f
@ -154,7 +154,8 @@
|
|||||||
|
|
||||||
## Developer info
|
## 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)
|
* [DNSControl is an opinionated system](opinions.md)
|
||||||
* [Writing new DNS providers](writing-providers.md)
|
* [Writing new DNS providers](writing-providers.md)
|
||||||
* [Creating new DNS Resource Types (rtypes)](adding-new-rtypes.md)
|
* [Creating new DNS Resource Types (rtypes)](adding-new-rtypes.md)
|
||||||
|
@ -60,14 +60,14 @@ a minimum.
|
|||||||
- Run stringer to auto-update the file `dnscontrol/providers/capability_string.go`
|
- Run stringer to auto-update the file `dnscontrol/providers/capability_string.go`
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
pushd; cd providers;
|
pushd; cd providers/;
|
||||||
stringer -type=Capability
|
stringer -type=Capability
|
||||||
popd
|
popd
|
||||||
```
|
```
|
||||||
alternatively
|
alternatively
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
pushd; cd providers;
|
pushd; cd providers/;
|
||||||
go generate
|
go generate
|
||||||
popd
|
popd
|
||||||
```
|
```
|
||||||
@ -180,7 +180,7 @@ See also `017-txt.js`.
|
|||||||
Run these tests via:
|
Run these tests via:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
cd dnscontrol/pkg/js
|
cd pkg/js/
|
||||||
go test ./...
|
go test ./...
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -252,7 +252,7 @@ in the source code.
|
|||||||
To run the integration test with the BIND provider:
|
To run the integration test with the BIND provider:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
cd dnscontrol/integrationTest
|
cd integrationTest/
|
||||||
go test -v -verbose -provider BIND
|
go test -v -verbose -provider BIND
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -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 %}
|
@ -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 %}
|
3
documentation/markdown-examples/hint/hint-danger.md
Normal file
3
documentation/markdown-examples/hint/hint-danger.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
{% hint style="danger" %}
|
||||||
|
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
|
||||||
|
{% endhint %}
|
3
documentation/markdown-examples/hint/hint-info.md
Normal file
3
documentation/markdown-examples/hint/hint-info.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
{% hint style="info" %}
|
||||||
|
**Info hints** are great for showing general information, or providing tips and tricks.
|
||||||
|
{% endhint %}
|
3
documentation/markdown-examples/hint/hint-success.md
Normal file
3
documentation/markdown-examples/hint/hint-success.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
{% hint style="success" %}
|
||||||
|
**Success hints** are good for showing positive actions or achievements.
|
||||||
|
{% endhint %}
|
3
documentation/markdown-examples/hint/hint-warning.md
Normal file
3
documentation/markdown-examples/hint/hint-warning.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
{% hint style="warning" %}
|
||||||
|
**Warning hints** are good for showing important information or non-critical warnings.
|
||||||
|
{% endhint %}
|
@ -57,7 +57,7 @@ dnscontrol get-zones --format=nameonly hexonet HEXONET all
|
|||||||
```
|
```
|
||||||
```shell
|
```shell
|
||||||
# Review the output. Pick one domain and set HEXONET_DOMAIN.
|
# 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_DOMAIN=yodream.com # Pick a domain name.
|
||||||
export HEXONET_ENTITY=OTE
|
export HEXONET_ENTITY=OTE
|
||||||
export HEXONET_UID=test.user
|
export HEXONET_UID=test.user
|
||||||
|
@ -235,7 +235,7 @@ Build the software:
|
|||||||
{% endhint %}
|
{% endhint %}
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
cd docs/flattener
|
cd docs/flattener/
|
||||||
export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)"
|
export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)"
|
||||||
export GOOS=linux
|
export GOOS=linux
|
||||||
gopherjs build
|
gopherjs build
|
||||||
|
201
documentation/styleguide-doc.md
Normal file
201
documentation/styleguide-doc.md
Normal file
@ -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. <https://dnscontrol.org/>
|
||||||
|
* 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. <https://docs.dnscontrol.org/>
|
||||||
|
* 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 <mark style="color:white;background-color:green;">line</mark>
|
||||||
|
{% 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 <https://www.google.com> 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.
|
@ -168,7 +168,6 @@ complex algorithms in the new code.
|
|||||||
|
|
||||||
Run the unit tests with this command:
|
Run the unit tests with this command:
|
||||||
|
|
||||||
cd dnscontrol
|
|
||||||
go test ./...
|
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:
|
For example, this will run the tests using BIND:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
cd dnscontrol/integrationTest
|
cd integrationTest/
|
||||||
go test -v -verbose -provider BIND
|
go test -v -verbose -provider BIND
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Reference in New Issue
Block a user