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

[Docs] improve contribute docs #5862

Merged
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
63 changes: 63 additions & 0 deletions docs/community/contribute/contribute_docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,66 @@ Deployment and API docs mostly use reStructured Text. For more information, see

You can cross-reference multiple Python modules, functions, classes, methods, and global data in documentations. For more information, see the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects).

### Quickstart

Flyte Documentation is primarily maintained in two locations: [flyte](https://github.com/flyteorg/flyte) and [flytesnacks](https://github.com/flyteorg/flytesnacks).

#### Tips
The following are some tips to include various content:
* **Images**
Flyte maintain all static resources in [static-resources-repo](https://github.com/flyteorg/static-resources).
You should upload your images to this repo and open the PR, and then refer to the image in the documentation.
Notice that the image URL should be in the format `https://raw.githubusercontent.com/flyteorg/static-resources/<git sha of your commit in PR>/<your image path>`.
* **Source code references (Link format)** <br>
`.rst` example:
```{code-block}
.. raw:: html

a href="https://github.com/flyteorg/<source repo name>/blob/<git sha>/<target file path>#L<from line>-L<to line>">View source code on GitHub</a>
```

`.md` example:
```{code-block}
[View source code on GitHub]("https://github.com/flyteorg/<source repo name>/blob/<git sha>/<target file path>#L<from line>-L<to line>")
```
* **Source code references (Embedded format)** <br>
`.rst` example:
```{code-block}
.. rli:: https://raw.githubusercontent.com/flyteorg/<source repo name>/<git sha>/<target file path>
:lines: <from line>-<to line>
```

`.md` example:
````{code-block}
```{rli} https://raw.githubusercontent.com/flyteorg/<source repo name>/<git sha>/<target file path>
lines: <from line>-<to line>
```
````

This way, the nested code block is properly displayed without breaking the Markdown structure.

#### Open a pull request
[This is an example PR](https://github.com/flyteorg/flyte/pull/5844)

Each time you update your PR, it triggers the CI build, so there’s no need to build the docs locally. Flyte uses the CI process `"docs/readthedocs.org:flyte"`, which builds the documentation after each PR.
Be sure to include the following CI-build preview link in your PR description so reviewers can easily preview the changes:
```{code-block}
https://flyte--<PR number>.org.readthedocs.build/en/<PR number>/<relative path>.html
```
The relative path is based on the `docs` directory.
For example, if the full path is `flyte/docs/user_guide/advanced_composition/chaining_flyte_entities.md`, then the relative path would be `user_guide/advanced_composition/chaining_flyte_entities` + `.html`.

#### Important note
In the `flytesnacks` repository, most Python comments using `# xxxx` are not imported into the documentation.
You may notice some overlap between `flytesnacks` and `flyte` docs, but what is displayed primarily comes from the`flyte` repository.

Otherwise, take care of the following points:
````{important}
* Make sure `:lines:` are aligned correctly.
* Use gitsha to specify the example code instead of using master branch or relative path, as this ensures 100% accuracy.
* Build the documentation by submitting a PR instead of building it locally.
* For `flytesnacks`, run `make fmt` before submitting the PR.
* Before uploading commits, use `git commit -s` to sign off. This step is often forgotten during the first submission.
* Run `codespell` on the modified files to check for any spelling mistakes before pushing.
* When using reference code or images, use gitsha along with GitHub raw content links.
````
Loading