dotnet / dotnet/iot

Improve generated documentation in docs.microsoft.com

Open
#1,836 2 comments 0 reactions 0 assignees View on GitHub
documentation Priority:2
Dominant language
C#
Stars
2.4k
Forks
630
Avg merge
11d 3h
Merged PRs (30d)
2

Description

Part of a continuous effort to improve the documentation, there are elements to be done to improve the all up experience:

- Add a reference to the readme from each binding folder to the source code of each main class
- should look like this in the intellisense comments: `[!INCLUDE[detailed usage](~/includes/Ads115/README.md)]`
- the folder name will have to match the name of the directory
- the file name is always READM.md as so far we only have this one
- in some cases like RTC, there are subfolder, follow the same subfolder strcture
- When creating a release the tool which will transform the READMEs need to be run. Tool located here: https://github.com/dotnet/iot/tree/main/tools/GenerateDocFxStructure
- the tool will create all the directories necessary, the sub directories if needed, move the README
- the tool will move as well all the images in another specific directory with a proper structure
- the tool will adjust all the necessary links from the pictures
- the tool will adjust all relative links to the repo to transform them into absolute links
- **all** the generated files need to be moved with the xml docs generated content for the PR into the iot-api-docs repository
- The [docfx.json](https://github.com/dotnet/iot-api-docs/blob/main/iot-api-docs/docfx.json) file from the iot-api-docs must be adjusted to include the new files as content (include and media), maybe other adjustments needed

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.