From d4b37c7c9d6735a071020b40df340aa522aac73a Mon Sep 17 00:00:00 2001 From: pseusys Date: Thu, 5 Oct 2023 11:55:36 +0200 Subject: [PATCH 1/2] doclinks added to contribution guide --- CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cdbe7baca..6c405e245 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,21 @@ WARNING! Because of the current patching solution, `make doc` modifies some of t so it is strongly advised to use it carefully and in virtual environment only. However, this behavior is likely to be changed in the future. +#### Documentation links + +In your tutprials, you can use special expanding directives in markdown cells. +They can help shorten the comments and avoid boilerplate code. +The documentation links generated by the directives are always relative and verified during build. + +- `%pip install {}` + This directive generates dependency installation cell, adds a comment and sets up "quiet" flag. + E.g. it should be used in tutorials, like this: `# %pip install dff[...]`. +- `%doclink({args})` + This directive generates a documentation link. It supports 2 or three arguments and the generated link will look like: `ARG1/ARG2#ARG3`. + NB! First argument can be either `api` for DFF codebase, `tutorial` for tutorials or `guide` for user guides. +- `%mddoclink({args})` + This directive is a shortcut for `%doclink` that generates a markdown format link instead, so that the output will be similar to `[ARG2](%doclink(ARG1,ARG2))` or `[ARG3](%doclink(ARG1,ARG2,ARG3))`. + ### Style For style supporting we propose `black`, which is a PEP 8 compliant opinionated formatter. It doesn't take previous formatting into account. See more about [black](https://github.com/psf/black). From 49a9647598457287c7bfa354d8e76a288dbe4254 Mon Sep 17 00:00:00 2001 From: Roman Zlobin Date: Wed, 11 Oct 2023 01:42:54 +0300 Subject: [PATCH 2/2] minor fixes --- CONTRIBUTING.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c405e245..eacd85ea4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,18 +69,23 @@ However, this behavior is likely to be changed in the future. #### Documentation links -In your tutprials, you can use special expanding directives in markdown cells. +In your tutorials, you can use special expanding directives in markdown cells. They can help shorten the comments and avoid boilerplate code. -The documentation links generated by the directives are always relative and verified during build. +The documentation links generated by the directives are always relative +to the local documentation and verified during build. -- `%pip install {}` - This directive generates dependency installation cell, adds a comment and sets up "quiet" flag. - E.g. it should be used in tutorials, like this: `# %pip install dff[...]`. +- `%pip install {args}` + This directive generates dependency installation cell, adds a comment and sets up "quiet" flag. + + It should be used in tutorials, like this: `# %pip install dff[...]`. - `%doclink({args})` - This directive generates a documentation link. It supports 2 or three arguments and the generated link will look like: `ARG1/ARG2#ARG3`. - NB! First argument can be either `api` for DFF codebase, `tutorial` for tutorials or `guide` for user guides. + This directive generates a documentation link. It supports 2 or three arguments and the generated link will look like: `ARG1/ARG2#ARG3`. + + The first argument can be either `api` for DFF codebase, `tutorial` for tutorials or `guide` for user guides. - `%mddoclink({args})` - This directive is a shortcut for `%doclink` that generates a markdown format link instead, so that the output will be similar to `[ARG2](%doclink(ARG1,ARG2))` or `[ARG3](%doclink(ARG1,ARG2,ARG3))`. + This directive is a shortcut for `%doclink` that generates a markdown format link instead. + + The generated link will be either `[ARG2](%doclink(ARG1,ARG2))` or `[ARG3](%doclink(ARG1,ARG2,ARG3))`. ### Style For style supporting we propose `black`, which is a PEP 8 compliant opinionated formatter.