Skip to content

Commit

Permalink
[Docs] improve contribute docs (#5862)
Browse files Browse the repository at this point in the history
Signed-off-by: DenChenn <[email protected]>
  • Loading branch information
DenChenn authored Oct 24, 2024
1 parent 5065f9b commit 6785887
Showing 1 changed file with 63 additions and 0 deletions.
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.
````

0 comments on commit 6785887

Please sign in to comment.