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.

Sign up for GitHub

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(contribute): rewrite flyte contribute docs based on 4960 #5260

Merged
merged 3 commits into from
Nov 13, 2024
Merged

docs(contribute): rewrite flyte contribute docs based on 4960 #5260

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ca91eb0
docs(contribute): rewrite flyte contribute docs based on 4960
bearomorphism Apr 21, 2024
fc28fef
docs(contribute): add conda setup back as an alternative
bearomorphism Apr 24, 2024
48db2cb
Merge branch 'master' into docs/flyte-make-dev-docs
bearomorphism Nov 12, 2024
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
34 changes: 30 additions & 4 deletions docs/community/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,12 +153,38 @@ To understand how the below components interact with each other, refer to :ref:`
* - **Purpose**: Deployment, Documentation, and Issues
* - **Languages**: RST

To build the Flyte docs locally you will need the following prerequisites:
In the ``flyteorg/flyte`` root directory you can run ``make dev-docs`` to build the documentation locally. The generated documentation will be in the ``docs/_build/html`` directory.

**Setup process**

1. First you need to make sure you can run linux/amd64 container
2. Run the following commands to build the documentation and serve it locally

.. prompt:: bash $

make dev-docs
python -m http.server --directory docs/_build/html

3. Go to http://localhost:8000 to see the documentation.

**Supported environment variables of** ``make dev-docs``

* ``DEV_DOCS_WATCH``: If set, the docs will be built and served using `sphinx-autobuild <https://github.com/sphinx-doc/sphinx-autobuild>`__ for live updates.
* ``FLYTEKIT_LOCAL_PATH``: If set, the local path to flytekit will be used instead of the source code from the ``flyteorg/flytekit repo``.
* ``FLYTECTL_LOCAL_PATH``: If set, the local path to flytectl will be used instead of the source code from the ``flyteorg/flytectl repo``.
* ``FLYTESNACKS_LOCAL_PATH``: If set, the local path to flytesnacks will be used instead of the source code from the ``flyteorg/flytesnacks`` repo.

For example, to use the local flytekit source code instead of the source code from the ``flyteorg/flytekit`` repo, run ``export FLYTEKIT_LOCAL_PATH=/path/to/flytekit`` before running ``make dev-docs``.

**Alternative conda setup steps**

* Install ``conda``.
* We recommend Miniconda installed with an `official installer <https://docs.conda.io/projects/miniconda/en/latest/index.html#latest-miniconda-installer-links>`__.
* Install `conda-lock <https://github.com/conda/conda-lock>`__.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we leave these steps in as an alternative to the steps below? You can move them down and put them in a "Alternative conda-lock setup steps" section.

Copy link
Contributor Author

@bearomorphism bearomorphism Apr 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but I am not sure how to build the Flyte doc by simply installing conda-lock. I guess this is only relevant to #4862, and we have to revert part of #4960 in order to make the alternative work.

@MortalHappiness Is conda-lock needed by make dev-docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bearomorphism No. conda-lock is not needed by using make dev-docs because it is already installed in the Dockerfile.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can add the following steps back as an alternative.

flyte/docs/community/contribute.rst

Lines 156 to 164 in 84c0fef

To build the Flyte docs locally you will need the following prerequisites:
* Install ``conda``.
* We recommend Miniconda installed with an `official installer <https://docs.conda.io/projects/miniconda/en/latest/index.html#latest-miniconda-installer-links>`__.
* Install `conda-lock <https://github.com/conda/conda-lock>`__.
* In the ``flyteorg/flyte`` root directory run:
* ``conda-lock install --name monodocs-env monodocs-environment.lock.yaml``
* ``conda activate monodocs-env``
* ``pip install ./flyteidl``

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

* In the ``flyteorg/flyte`` root directory you can run:
* ``make dev-docs`` to build the documentation locally. The build will be in the ``docs/_build/html`` directory. See `the script <https://github.com/flyteorg/flyte/blob/master/script/local_build_docs.sh>`__ for additional environment variables that can be set.
* For example, to use the local flytekit source code instead of the source code from the flyteorg/flytekit repo, run ``export FLYTEKIT_LOCAL_PATH=/path/to/flytekit`` before running ``make dev-docs``.
* In the ``flyteorg/flyte`` root directory run:
* ``conda-lock install --name monodocs-env monodocs-environment.lock.yaml``
* ``conda activate monodocs-env``
* ``pip install ./flyteidl``

``flyteidl``
************
Expand Down
Loading