From 5cc3aaaa5dcfbe62eed6a7c3d2e3f30c81c58eab Mon Sep 17 00:00:00 2001 From: DenChenn Date: Fri, 18 Oct 2024 20:49:16 +0800 Subject: [PATCH] [Docs] improve contribute docs Signed-off-by: DenChenn --- docs/community/contribute/contribute_docs.md | 61 ++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/community/contribute/contribute_docs.md b/docs/community/contribute/contribute_docs.md index 3b5d996abf6..ef1c173e5d4 100644 --- a/docs/community/contribute/contribute_docs.md +++ b/docs/community/contribute/contribute_docs.md @@ -57,3 +57,64 @@ 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//`. +* **Source code references (Link format)** + `.rst` example: + ```{code-block} + .. raw:: html + + a href="https://github.com/flyteorg//blob//#L-L">View source code on GitHub + ``` + + `.md` example: + ```{code-block} + [View source code on GitHub]("https://github.com/flyteorg//blob//#L-L") + ``` +* **Source code references (Embedded format)** + `.rst` example: + ```{code-block} + .. rli:: https://raw.githubusercontent.com/flyteorg/// + :lines: - + ``` + + `.md` example: + ```{code-block} + ```{rli} https://raw.githubusercontent.com/flyteorg/// + lines: - + ``` + ``` + +#### 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--.org.readthedocs.build/en//.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. +````