Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doclinks added to contribution guide #245

Merged
merged 2 commits into from
Oct 16, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Loading