1
0
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:
Jeffrey Cafferata
2023-05-22 13:31:30 +02:00
committed by GitHub
parent cfcc451089
commit 9a3cd8e26f
13 changed files with 242 additions and 9 deletions

View File

@ -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)

View File

@ -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
```

View File

@ -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 %}

View File

@ -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 %}

View File

@ -0,0 +1,3 @@
{% hint style="danger" %}
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
{% endhint %}

View File

@ -0,0 +1,3 @@
{% hint style="info" %}
**Info hints** are great for showing general information, or providing tips and tricks.
{% endhint %}

View File

@ -0,0 +1,3 @@
{% hint style="success" %}
**Success hints** are good for showing positive actions or achievements.
{% endhint %}

View File

@ -0,0 +1,3 @@
{% hint style="warning" %}
**Warning hints** are good for showing important information or non-critical warnings.
{% endhint %}

View File

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

View File

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

View 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.

View File

@ -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
```