From 441899cfab2e028abc410bed89785417fe69b370 Mon Sep 17 00:00:00 2001 From: Alexander Sergeev Date: Mon, 16 Oct 2023 22:31:44 +0200 Subject: [PATCH] Doclinks added to contribution guide (#245) * doclinks added to contribution guide * minor fixes --------- Co-authored-by: Roman Zlobin --- CONTRIBUTING.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cdbe7baca..eacd85ea4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,26 @@ 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 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 +to the local documentation and verified during build. + +- `%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`. + + 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. + + 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. It doesn't take previous formatting into account. See more about [black](https://github.com/psf/black).