Re: [PR] Improve documentation building iteration [airflow]

2025-04-07 Thread via GitHub 


eladkal commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030652134


##
.gitignore:
##
@@ -261,8 +267,3 @@ airflow-build-dockerfile*
 *.zip
 
 _api/
-
-# Items generated when building the docs locally for release
-/docs/_build/
-/docs/_doctrees/*/
-/docs/_inventory_cache/

Review Comment:
   @potiuk providers doc files are built in `docs/` path
   removing it causes many untracked files.
   ![Screenshot 2025-04-07 at 10 48 
27](https://github.com/user-attachments/assets/f2cfd1a2-32dd-4deb-96bc-98789f59cef2)
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-07 Thread via GitHub 


eladkal commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030652134


##
.gitignore:
##
@@ -261,8 +267,3 @@ airflow-build-dockerfile*
 *.zip
 
 _api/
-
-# Items generated when building the docs locally for release
-/docs/_build/
-/docs/_doctrees/*/
-/docs/_inventory_cache/

Review Comment:
   @potiuk providers doc files are built in `docs/` path
   removing it causes many untracked files.
   ![Screenshot 2025-04-07 at 10 48 
27](https://github.com/user-attachments/assets/f2cfd1a2-32dd-4deb-96bc-98789f59cef2)
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-06 Thread via GitHub 


potiuk merged PR #48760:
URL: https://github.com/apache/airflow/pull/48760


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-06 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030181494


##
pyproject.toml:
##
@@ -780,7 +780,7 @@ banned-module-level-imports = ["numpy", "pandas"]
 "locale.getdefaultlocale".msg = "Use locale.setlocale() and locale.getlocale() 
instead."
 # Deprecated in Python 3.12: https://github.com/python/cpython/issues/103857
 "datetime.datetime.utcnow".msg = "Use airflow.utils.timezone.utcnow or 
datetime.datetime.now(tz=datetime.timezone.utc)"
-"datetime.datetime.utcfromtimestamp".msg = "Use 
airflow.utils.timezone.from_timestamp or 
datetime.datetime.fromtimestamp(tz=datetime.timezone.utc)"
+"datetime.datetimedatetime.utcfromtimestamp".msg = "Use 
airflow.utils.timezone.from_timestamp or 
datetime.datetime.fromtimestamp(tz=datetime.timezone.utc)"

Review Comment:
   Must have been some accidental copy* paste
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-06 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030181366


##
providers-summary-docs/pyproject.toml:
##
@@ -0,0 +1,81 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[build-system]
+requires = [
+"hatchling==1.27.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "apache-airflow-providers"
+description = "Programmatically author, schedule and monitor data pipelines"
+requires-python = "~=3.9,<3.13"
+authors = [
+{ name = "Apache Software Foundation", email = "d...@airflow.apache.org" },
+]
+maintainers = [
+{ name = "Apache Software Foundation", email="d...@airflow.apache.org" },
+]
+keywords = [ "airflow", "orchestration", "workflow", "dag", "pipelines", 
"automation", "data" ]
+classifiers = [
+"Development Status :: 5 - Production/Stable",
+"Environment :: Console",
+"Environment :: Web Environment",
+"Framework :: Apache Airflow",
+"Intended Audience :: Developers",
+"Intended Audience :: System Administrators",
+"License :: OSI Approved :: Apache Software License",
+"Programming Language :: Python :: 3.9",
+"Programming Language :: Python :: 3.10",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Topic :: System :: Monitoring",
+"Topic :: System :: Monitoring",
+]
+
+version = "0.0.1"
+
+dependencies = [
+"apache-airflow-core",
+"apache-airflow-devel-common",
+]

Review Comment:
   No - not really. We do not have any "source" dependency between them. The 
only reason we have those dependencies here is to make sure "airflow" and 
"devel-common" is available on the path and has all the deps installed wheen 
``uv run`` is used in that folder.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-06 Thread via GitHub 


gopidesupavan commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030179283


##
pyproject.toml:
##
@@ -780,7 +780,7 @@ banned-module-level-imports = ["numpy", "pandas"]
 "locale.getdefaultlocale".msg = "Use locale.setlocale() and locale.getlocale() 
instead."
 # Deprecated in Python 3.12: https://github.com/python/cpython/issues/103857
 "datetime.datetime.utcnow".msg = "Use airflow.utils.timezone.utcnow or 
datetime.datetime.now(tz=datetime.timezone.utc)"
-"datetime.datetime.utcfromtimestamp".msg = "Use 
airflow.utils.timezone.from_timestamp or 
datetime.datetime.fromtimestamp(tz=datetime.timezone.utc)"
+"datetime.datetimedatetime.utcfromtimestamp".msg = "Use 
airflow.utils.timezone.from_timestamp or 
datetime.datetime.fromtimestamp(tz=datetime.timezone.utc)"

Review Comment:
   `datetimedatetime ` is this intentionally changed or mistake?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-06 Thread via GitHub 


gopidesupavan commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030178506


##
providers-summary-docs/pyproject.toml:
##
@@ -0,0 +1,81 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[build-system]
+requires = [
+"hatchling==1.27.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "apache-airflow-providers"
+description = "Programmatically author, schedule and monitor data pipelines"
+requires-python = "~=3.9,<3.13"
+authors = [
+{ name = "Apache Software Foundation", email = "d...@airflow.apache.org" },
+]
+maintainers = [
+{ name = "Apache Software Foundation", email="d...@airflow.apache.org" },
+]
+keywords = [ "airflow", "orchestration", "workflow", "dag", "pipelines", 
"automation", "data" ]
+classifiers = [
+"Development Status :: 5 - Production/Stable",
+"Environment :: Console",
+"Environment :: Web Environment",
+"Framework :: Apache Airflow",
+"Intended Audience :: Developers",
+"Intended Audience :: System Administrators",
+"License :: OSI Approved :: Apache Software License",
+"Programming Language :: Python :: 3.9",
+"Programming Language :: Python :: 3.10",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Topic :: System :: Monitoring",
+"Topic :: System :: Monitoring",
+]
+
+version = "0.0.1"
+
+dependencies = [
+"apache-airflow-core",
+"apache-airflow-devel-common",
+]

Review Comment:
   docker-stack and helm-chart is not required? 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


potiuk commented on PR #48760:
URL: https://github.com/apache/airflow/pull/48760#issuecomment-2781230119

   Would love one last pass over the latest changes  - I think it's ready to 
merge now.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2030043052


##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+Building documentation
+==
+
+Airflow uses Sphinx to build the documentation. As of Airflow 3 when we split
+the distributions into multiple packages, and moved the documentation to 
inside those
+distribution building the documentation is way easier than it was on Airflow 2 
and you
+can usually iterate on documentation way faster, including automatically 
refreshing the
+documentation in your browser when using ``sphinx-autobuild``.
+
+The current distributions we have that have sphinx-buildable documentation are:
+
+Documentation in separate distributions:
+
+* ``airflow-core/docs`` - documentation for Airflow Core
+* ``providers/**/docs`` - documentation for Providers
+* ``chart/docs`` - documentation for Helm Chart
+* ``task-sdk/docs`` - documentation for Task SDK (new format not yet published)
+* ``airflow-ctl/docs`` - documentation for Airflow CLI (future)
+
+Documentation for general overview and summaries not connected with amy 
specific distribution:
+
+* ``docker-stack-docs`` - documentation for Docker Stack'
+* ``providers-summary-docs`` - documentation for provider summary page
+
+
+Building documentation with uv in local venv
+
+
+Prerequisites
+.
+
+First of all. you need to have ``uv`` installed. You can very easily build the 
documentation
+in your local virtualenv using ``uv`` command.
+
+.. warning::
+
+   There is a prerequisite needed to build the documentation locally. 
Airflow's Sphinx configuration
+   depends on ``enchant`` C-library that needs to be installed and configured 
to be used by ``pyenchant``
+   Python distribution package. You can install it as explained in the
+   `pyenchant documentation 
`__. Usually you use your
+   package manager on Linux or ``brew`` on ``MacOS``. Sometimes you might also 
need to configure it
+   so that ``pyenchant`` can find the dictionary files. You will get error 
like:
+
+   .. code-block:: txt
+
+   Could not import extension sphinxcontrib.spelling (exception: The 
'enchant' C library was not
+   found and maybe needs to be installed
+
+   In this case the easiest way is to find where your enchant library is 
(usually libenchant-2.dylib)
+   and set the ``PYENCHANT_LIBRARY_PATH`` environment variable to that path in 
your ``.zshrc`` or ``.bashrc``
+   - depending which terminal you use and restart your terminal. For example 
on MacOS,
+   ``brew install enchant`` or ``brew reinstall enchant`` will print the path 
where enchant is
+   installed and usually the library is in the ``lib`` subfolder of it. An 
example of line added
+   to one of the ``.rc`` files:
+
+   .. code-block:: bash
+
+  export 
PYENCHANT_LIBRARY_PATH=/opt/homebrew/Cellar/enchant/2.8.2/lib/libenchant-2.dylib
+
+   Also for some of the providers you might need to have trouble in installing 
dependencies. The ``uv run``
+   command will automatically install the needed dependencies for you but some 
of them might need extra
+   system dependencies. You can always revert to ``breeze`` way of building 
the documentation in this
+   case (see below) in case you have problems with ``uv run`` command not 
being able to install
+   the dependencies.
+
+Once you have enchant installed and configured, you can build the 
documentation very easily.
+
+
+
+First thing to do, is to sync the inter-sphinx inventory. You can do it only 
once and refresh it periodically
+when you find that your documentation cannot be build because of missing 
inter-sphinx inventory or links
+The inventory is basically a list of links to other documentation that is used 
in the Airflow documentation
+and our build issues warnings if the inventory links are missing.
+
+.. code-block:: bash
+
+cd devel-common
+uv run src/sphinx_exts/docs_build/fetch_inventories.py
+
+When you want to refresh the inventory, you can run the same command with 
``cle

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


potiuk commented on PR #48760:
URL: https://github.com/apache/airflow/pull/48760#issuecomment-2781139438

   OK. I improve it way more. Rather than using sphinx commands directly, I 
repurposed the `docs_build.py` into a `doc-build` command line that you can use 
now to build documentation locally.
   
   ```bash
   cd FOLDER
   uv run --group docs build-docs 
   ```
   
   Then in order to get automatically refreshing server:
   
   ```bash
   cd FOLDER
   uv run --group docs build-docs --autobuild
   ```
   
   But also you can build several packages together (including solving updated 
cross-package doc  references) 
   
   ```bash
   uv run --group docs build-docs PACKAGE1 PACKAGE 2
   ```
   
   Or even build docs for all packages together (when run in the top directory):
   
   ```bash
   uv run --group docs build-docs
   ```
   
   The tool to build docs has now nice `rich-click` interface:
   
   https://github.com/user-attachments/assets/a9623823-8099-4e26-965e-cb1313a37c32";
 />
   
   
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


o-nikolas commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2027566087


##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+Building documentation
+==
+
+Airflow uses Sphinx to build the documentation. As of Airflow 3 when we split
+the distributions into multiple packages, and moved the documentation to 
inside those
+distribution building the documentation is way easier than it was on Airflow 2 
and you
+can usually iterate on documentation way faster, including automatically 
refreshing the
+documentation in your browser when using ``sphinx-autobuild``.
+
+The current distributions we have that have sphinx-buildable documentation are:
+
+Documentation in separate distributions:
+
+* ``airflow-core/docs`` - documentation for Airflow Core
+* ``providers/**/docs`` - documentation for Providers
+* ``chart/docs`` - documentation for Helm Chart
+* ``task-sdk/docs`` - documentation for Task SDK (new format not yet published)
+* ``airflow-ctl/docs`` - documentation for Airflow CLI (future)
+
+Documentation for general overview and summaries not connected with amy 
specific distribution:
+
+* ``docker-stack-docs`` - documentation for Docker Stack'
+* ``providers-summary-docs`` - documentation for provider summary page
+
+
+Building documentation with uv in local venv
+
+
+Prerequisites
+.
+
+First of all. you need to have ``uv`` installed. You can very easily build the 
documentation
+in your local virtualenv using ``uv`` command.
+
+.. warning::
+
+   There is a prerequisite needed to build the documentation locally. 
Airflow's Sphinx configuration
+   depends on ``enchant`` C-library that needs to be installed and configured 
to be used by ``pyenchant``
+   Python distribution package. You can install it as explained in the
+   `pyenchant documentation 
`__. Usually you use your
+   package manager on Linux or ``brew`` on ``MacOS``. Sometimes you might also 
need to configure it
+   so that ``pyenchant`` can find the dictionary files. You will get error 
like:
+
+   .. code-block:: txt
+
+   Could not import extension sphinxcontrib.spelling (exception: The 
'enchant' C library was not
+   found and maybe needs to be installed
+
+   In this case the easiest way is to find where your enchant library is 
(usually libenchant-2.dylib)
+   and set the ``PYENCHANT_LIBRARY_PATH`` environment variable to that path in 
your ``.zshrc`` or ``.bashrc``
+   - depending which terminal you use and restart your terminal. For example 
on MacOS,
+   ``brew install enchant`` or ``brew reinstall enchant`` will print the path 
where enchant is
+   installed and usually the library is in the ``lib`` subfolder of it. An 
example of line added
+   to one of the ``.rc`` files:
+
+   .. code-block:: bash
+
+  export 
PYENCHANT_LIBRARY_PATH=/opt/homebrew/Cellar/enchant/2.8.2/lib/libenchant-2.dylib
+
+   Also for some of the providers you might need to have trouble in installing 
dependencies. The ``uv run``

Review Comment:
   ```suggestion
  Also for some of the providers you might have trouble installing 
dependencies. The ``uv run``
   ```



##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permiss

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


vincbeck commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2027502683


##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+Building documentation
+==
+
+Airflow uses Sphinx to build the documentation. As of Airflow 3 when we split
+the distributions into multiple packages, and moved the documentation to 
inside those
+distribution building the documentation is way easier than it was on Airflow 2 
and you
+can usually iterate on documentation way faster, including automatically 
refreshing the
+documentation in your browser when using ``sphinx-autobuild``.
+
+The current distributions we have that have sphinx-buildable documentation are:
+
+Documentation in separate distributions:
+
+* ``airflow-core/docs`` - documentation for Airflow Core
+* ``providers/**/docs`` - documentation for Providers
+* ``chart/docs`` - documentation for Helm Chart
+* ``task-sdk/docs`` - documentation for Task SDK (new format not yet published)
+* ``airflow-ctl/docs`` - documentation for Airflow CLI (future)
+
+Documentation for general overview and summaries not connected with amy 
specific distribution:

Review Comment:
   ```suggestion
   Documentation for general overview and summaries not connected with any 
specific distribution:
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-05 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2028463493


##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+Building documentation
+==
+
+Airflow uses Sphinx to build the documentation. As of Airflow 3 when we split
+the distributions into multiple packages, and moved the documentation to 
inside those
+distribution building the documentation is way easier than it was on Airflow 2 
and you
+can usually iterate on documentation way faster, including automatically 
refreshing the
+documentation in your browser when using ``sphinx-autobuild``.
+
+The current distributions we have that have sphinx-buildable documentation are:
+
+Documentation in separate distributions:
+
+* ``airflow-core/docs`` - documentation for Airflow Core
+* ``providers/**/docs`` - documentation for Providers
+* ``chart/docs`` - documentation for Helm Chart
+* ``task-sdk/docs`` - documentation for Task SDK (new format not yet published)
+* ``airflow-ctl/docs`` - documentation for Airflow CLI (future)
+
+Documentation for general overview and summaries not connected with amy 
specific distribution:
+
+* ``docker-stack-docs`` - documentation for Docker Stack'
+* ``providers-summary-docs`` - documentation for provider summary page
+
+
+Building documentation with uv in local venv
+
+
+Prerequisites
+.
+
+First of all. you need to have ``uv`` installed. You can very easily build the 
documentation
+in your local virtualenv using ``uv`` command.
+
+.. warning::
+
+   There is a prerequisite needed to build the documentation locally. 
Airflow's Sphinx configuration
+   depends on ``enchant`` C-library that needs to be installed and configured 
to be used by ``pyenchant``
+   Python distribution package. You can install it as explained in the
+   `pyenchant documentation 
`__. Usually you use your
+   package manager on Linux or ``brew`` on ``MacOS``. Sometimes you might also 
need to configure it
+   so that ``pyenchant`` can find the dictionary files. You will get error 
like:
+
+   .. code-block:: txt
+
+   Could not import extension sphinxcontrib.spelling (exception: The 
'enchant' C library was not
+   found and maybe needs to be installed
+
+   In this case the easiest way is to find where your enchant library is 
(usually libenchant-2.dylib)
+   and set the ``PYENCHANT_LIBRARY_PATH`` environment variable to that path in 
your ``.zshrc`` or ``.bashrc``
+   - depending which terminal you use and restart your terminal. For example 
on MacOS,
+   ``brew install enchant`` or ``brew reinstall enchant`` will print the path 
where enchant is
+   installed and usually the library is in the ``lib`` subfolder of it. An 
example of line added
+   to one of the ``.rc`` files:
+
+   .. code-block:: bash
+
+  export 
PYENCHANT_LIBRARY_PATH=/opt/homebrew/Cellar/enchant/2.8.2/lib/libenchant-2.dylib
+
+   Also for some of the providers you might need to have trouble in installing 
dependencies. The ``uv run``
+   command will automatically install the needed dependencies for you but some 
of them might need extra
+   system dependencies. You can always revert to ``breeze`` way of building 
the documentation in this
+   case (see below) in case you have problems with ``uv run`` command not 
being able to install
+   the dependencies.
+
+Once you have enchant installed and configured, you can build the 
documentation very easily.
+
+
+
+First thing to do, is to sync the inter-sphinx inventory. You can do it only 
once and refresh it periodically
+when you find that your documentation cannot be build because of missing 
inter-sphinx inventory or links
+The inventory is basically a list of links to other documentation that is used 
in the Airflow documentation
+and our build issues warnings if the inventory links are missing.
+
+.. code-block:: bash
+
+cd devel-common
+uv run src/sphinx_exts/docs_build/fetch_inventories.py
+
+When you want to refresh the inventory, you can run the same command with 
``cle

Re: [PR] Improve documentation building iteration [airflow]

2025-04-04 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2028468728


##
contributing-docs/11_documentation_building.rst:
##
@@ -0,0 +1,160 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+Building documentation
+==
+
+Airflow uses Sphinx to build the documentation. As of Airflow 3 when we split
+the distributions into multiple packages, and moved the documentation to 
inside those
+distribution building the documentation is way easier than it was on Airflow 2 
and you
+can usually iterate on documentation way faster, including automatically 
refreshing the
+documentation in your browser when using ``sphinx-autobuild``.
+
+The current distributions we have that have sphinx-buildable documentation are:
+
+Documentation in separate distributions:
+
+* ``airflow-core/docs`` - documentation for Airflow Core
+* ``providers/**/docs`` - documentation for Providers
+* ``chart/docs`` - documentation for Helm Chart
+* ``task-sdk/docs`` - documentation for Task SDK (new format not yet published)
+* ``airflow-ctl/docs`` - documentation for Airflow CLI (future)
+
+Documentation for general overview and summaries not connected with amy 
specific distribution:
+
+* ``docker-stack-docs`` - documentation for Docker Stack'
+* ``providers-summary-docs`` - documentation for provider summary page
+
+
+Building documentation with uv in local venv
+
+
+Prerequisites
+.
+
+First of all. you need to have ``uv`` installed. You can very easily build the 
documentation
+in your local virtualenv using ``uv`` command.
+
+.. warning::
+
+   There is a prerequisite needed to build the documentation locally. 
Airflow's Sphinx configuration
+   depends on ``enchant`` C-library that needs to be installed and configured 
to be used by ``pyenchant``
+   Python distribution package. You can install it as explained in the
+   `pyenchant documentation 
`__. Usually you use your
+   package manager on Linux or ``brew`` on ``MacOS``. Sometimes you might also 
need to configure it
+   so that ``pyenchant`` can find the dictionary files. You will get error 
like:
+
+   .. code-block:: txt
+
+   Could not import extension sphinxcontrib.spelling (exception: The 
'enchant' C library was not
+   found and maybe needs to be installed
+
+   In this case the easiest way is to find where your enchant library is 
(usually libenchant-2.dylib)
+   and set the ``PYENCHANT_LIBRARY_PATH`` environment variable to that path in 
your ``.zshrc`` or ``.bashrc``
+   - depending which terminal you use and restart your terminal. For example 
on MacOS,
+   ``brew install enchant`` or ``brew reinstall enchant`` will print the path 
where enchant is
+   installed and usually the library is in the ``lib`` subfolder of it. An 
example of line added
+   to one of the ``.rc`` files:
+
+   .. code-block:: bash
+
+  export 
PYENCHANT_LIBRARY_PATH=/opt/homebrew/Cellar/enchant/2.8.2/lib/libenchant-2.dylib
+
+   Also for some of the providers you might need to have trouble in installing 
dependencies. The ``uv run``
+   command will automatically install the needed dependencies for you but some 
of them might need extra
+   system dependencies. You can always revert to ``breeze`` way of building 
the documentation in this
+   case (see below) in case you have problems with ``uv run`` command not 
being able to install
+   the dependencies.
+
+Once you have enchant installed and configured, you can build the 
documentation very easily.
+
+
+
+First thing to do, is to sync the inter-sphinx inventory. You can do it only 
once and refresh it periodically
+when you find that your documentation cannot be build because of missing 
inter-sphinx inventory or links
+The inventory is basically a list of links to other documentation that is used 
in the Airflow documentation
+and our build issues warnings if the inventory links are missing.
+
+.. code-block:: bash
+
+cd devel-common
+uv run src/sphinx_exts/docs_build/fetch_inventories.py
+
+When you want to refresh the inventory, you can run the same command with 
``cle

Re: [PR] Improve documentation building iteration [airflow]

2025-04-04 Thread via GitHub 


potiuk commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2028469413


##
contributing-docs/16_adding_api_endpoints.rst:
##
@@ -108,3 +108,7 @@ When migrating legacy endpoint to the new FastAPI API:
 1. Implement a feature complete endpoint in comparison to the legacy one or 
explain why this is not possible in your context.
 2. Make sure to have a good test coverage by copying over the legacy test 
cases to the new endpoint. This will guarantee an isofunctional new endpoint.
 3. Mark the legacy endpoint with the ``@mark_fastapi_migration_done`` 
decorator. This will help maintainers keep track of the endpoints remaining for 
the migration and those already migrated.
+
+00

Review Comment:
   It's 👀 
   
   No.. on a serious note, it's of course typo :)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Re: [PR] Improve documentation building iteration [airflow]

2025-04-03 Thread via GitHub 


rawwar commented on code in PR #48760:
URL: https://github.com/apache/airflow/pull/48760#discussion_r2028059084


##
chart/pyproject.toml:
##
@@ -0,0 +1,80 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[build-system]
+requires = [
+"hatchling==1.27.0",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "apache-airflow-helm-chart"
+description = "Programmatically author, schedule and monitor data pipelines"
+requires-python = "~=3.9,<3.13"
+authors = [
+{ name = "Apache Software Foundation", email = "d...@airflow.apache.org" },
+]
+maintainers = [
+{ name = "Apache Software Foundation", email="d...@airflow.apache.org" },
+]
+keywords = [ "airflow", "orchestration", "workflow", "dag", "pipelines", 
"automation", "data" ]
+classifiers = [
+"Development Status :: 5 - Production/Stable",
+"Environment :: Console",
+"Environment :: Web Environment",
+"Framework :: Apache Airflow",
+"Intended Audience :: Developers",
+"Intended Audience :: System Administrators",
+"License :: OSI Approved :: Apache Software License",
+"Programming Language :: Python :: 3.9",
+"Programming Language :: Python :: 3.10",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Topic :: System :: Monitoring",
+"Topic :: System :: Monitoring",
+]
+
+version = "0.0.1"
+
+dependencies = [
+"apache-airflow-core",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["*"]
+
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[dependency-groups]
+# To run docs building run:

Review Comment:
   ```suggestion
   # To build docs, run:
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org