@@ -1,18 +1,18 @@ | |||||
# Contributing to Docs | # Contributing to Docs | ||||
I don't really have any strict conditions for writing documentation, | |||||
We don't really have any strict conditions for writing documentation, | |||||
but just keep these few guidelines in mind: | but just keep these few guidelines in mind: | ||||
* Keep code samples in the `guides/samples` folder | * Keep code samples in the `guides/samples` folder | ||||
* When referencing an object in the API, link to it's page in the | |||||
API documentation. | |||||
* When referencing an object in the API, link to it's page in the | |||||
API documentation. | |||||
* Documentation should be written in clear and proper English* | * Documentation should be written in clear and proper English* | ||||
\* If anyone is interested in translating documentation into other | |||||
languages, please open an issue or contact me on | |||||
\* If anyone is interested in translating documentation into other | |||||
languages, please open an issue or contact me on | |||||
Discord (`foxbot#0282`). | Discord (`foxbot#0282`). | ||||
### Layout | |||||
## Layout | |||||
Documentation should be written in a FAQ/Wiki style format. | Documentation should be written in a FAQ/Wiki style format. | ||||
@@ -33,14 +33,4 @@ Example of long link syntax: | |||||
Please consult the [API Documentation] for more information. | Please consult the [API Documentation] for more information. | ||||
[API Documentation]: xref:System.String | [API Documentation]: xref:System.String | ||||
``` | |||||
### Compiling | |||||
Documentation is compiled into a static site using [DocFx]. | |||||
We currently use the most recent build off the dev branch. | |||||
After making changes, compile your changes into the static site with | |||||
`docfx`. You can also view your changes live with `docfx --serve`. | |||||
[DocFx]: https://dotnet.github.io/docfx/ | |||||
``` |
@@ -1,16 +1,16 @@ | |||||
# Instructions for Building Documentation | # Instructions for Building Documentation | ||||
The documentation for the Discord.Net library uses [DocFX][docfx-main]. [Instructions for installing this tool can be found here.][docfx-installing] | |||||
The documentation for the Discord.Net library uses [DocFX][docfx-main]. | |||||
[Instructions for installing this tool can be found here.][docfx-installing] | |||||
1. Navigate to the root of the repository. | 1. Navigate to the root of the repository. | ||||
2. (Optional) If you intend to target a specific version, ensure that you | |||||
have the correct version checked out. | |||||
3. Build the library. Run `dotnet build` in the root of this repository. | |||||
Ensure that the build passes without errors. | |||||
4. Build the docs using `docfx .\docs\docfx.json`. Add the `--serve` parameter | |||||
to preview the site locally. Some elements of the page may appear incorrect | |||||
when not hosted by a server. | |||||
- Remarks: According to the docfx website, this tool does work on Linux under mono. | |||||
2. (Optional) If you intend to target a specific version, ensure that | |||||
you have the correct version checked out. | |||||
3. Build the docs using `docfx docs/docfx.json`. Add the `--serve` | |||||
parameter to preview the site locally. Some elements of the page | |||||
may appear incorrect when not hosted by a server. | |||||
- Remarks: According to the docfx website, this tool does work on | |||||
Linux under Mono. | |||||
[docfx-main]: https://dotnet.github.io/docfx/ | [docfx-main]: https://dotnet.github.io/docfx/ | ||||
[docfx-installing]: https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html | [docfx-installing]: https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html |