From 3d7282c2bda958148be26d5198300c8735e099da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?= Date: Fri, 2 Aug 2019 10:57:32 +0200 Subject: [PATCH] Add a section on documentation to contributing.md Related to #1695 --- docs/contributing.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index cf66f0e2..d651d448 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -5,6 +5,7 @@ [Branches](#branches)
[Directory structure](#directory-structure)
[Testing your changes](#testing-your-changes)
+[Documenting your code](#documenting-your-code)
[Code constructs to watch out for](#code-constructs-to-watch-out-for)
So you want to contribute something to Catch? That's great! Whether it's a bug fix, a new feature, support for @@ -81,6 +82,51 @@ before you do so, you need to check that the introduced changes are indeed intentional. +## Documenting your code + +If you have added new feature to Catch2, it needs documentation, so that +other people can use it as well. This section collects some technical +information that you will need for updating Catch2's documentation, and +possibly some generic advise as well. + +First, the technicalities: + +* We introduced version tags to the documentation, which show users in +which version a specific feature was introduced. This means that newly +written documentation should be tagged with a placeholder, that will +be replaced with the actual version upon release. There are 2 styles +of placeholders used through the documentation, you should pick one that +fits your text better (if in doubt, take a look at the existing version +tags for other features). + * `> [Introduced](link-to-issue-or-PR) in Catch X.Y.Z` - this + placeholder is usually used after a section heading + * `> X (Y and Z) was [introduced](link-to-issue-or-PR) in Catch X.Y.Z` + - this placeholder is used when you need to tag a subpart of something, + e.g. list +* Crosslinks to different pages should target the `top` anchor, like this +`[link to contributing](contributing.md#top)`. +* If you have introduced a new document, please add a a `top` anchor at +the top, like this +```markdown + +# Contributing to Catch +``` +* For pages with more than 4 subheadings, we provide a table of contents +(ToC) at the top of the page. Because GitHub markdown does not support +automatic generation of ToC, it has to be handled semi-manually. Thus, +if you've added a new subheading to some page, you should add it to the +ToC. This can be done either manually, or by running the +`updateDocumentToC.py` script in the `scripts/` folder. + + +Now, for the generic tips: + * Usage examples are good + * Don't be afraid to introduce new pages + * Try to be reasonably consistent with the surrounding documentation + + + + ## Code constructs to watch out for This section is a (sadly incomplete) listing of various constructs that