Skip to content

Latest commit

 

History

History
42 lines (30 loc) · 3.01 KB

README.md

File metadata and controls

42 lines (30 loc) · 3.01 KB

Contributing to the Documentation

This folder contains the documentation site for bUnit.

Here is a small getting started guide for contributing to the documentation...

Structures

  1. The site folder contains the code for generating the documentation site, and the documentation in markdown files, located in site/docs.
  2. The samples folder projects for the sample code that is displayed in the documentation. It has the following projects:
  • samples/components: A Blazor component library project where components under test are placed.
  • samples/tests/mstest: An MSTest project where MSTest test samples are placed.
  • samples/tests/nunit: An NUnit project where NUnit test samples are placed.
  • samples/tests/razor: An xUnit-based test project where razor test samples are placed.
  • samples/tests/xunit: An xUnit project where xUnit C#-only test samples are placed.

These sample components, source files, and tests source files are included in the documentation using DocFx's Code Snippet syntax. They are created as real projects, making them runnable, which helps ensure that the code samples shown in the documentation pages are correct and in working order.

Building and Viewing Docs Locally

The following chapter describes how you can run and view the documentation locally

Requirements

The following tools are required to build and view the documentation locally:

View the documentation

  1. Build the bunit.sln solution in the root folder in release configuration dotnet build -c Release.
  2. From docs/site run docfx metadata to generate the documentation site's metadata.
  3. After that run docfx build to generate the documentation site.
  4. From docs/ run serve-docs.cmd. This will start up a local web server (using dotnet serve), hosting the generated documentation site.
  5. After changing samples from docs/samples, run dotnet test. This will compile the sample components and run the sample tests.

Documentation Writing Rules

  • All pages should have a YAML header with a UID to make it easy to cross reference between pages
  • All page and code references should be created using the xref:UID cross reference syntax.
  • By default, you should include code snippets as sample files in the samples projects, using the code snippet syntax.
  • All code snippets should use 2 spaces as an indention unit (1 tab = 2 spaces).