You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2021/12/01 10:46:53 UTC
[GitHub] [arrow] AlenkaF opened a new pull request #11823: ARROW-14761: [Doc] Helping with documentation
AlenkaF opened a new pull request #11823:
URL: https://github.com/apache/arrow/pull/11823
Add **Helping with documentation** section of the New Contributor's guide.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-986568810
@jorisvandenbossche @pitrou I added the suggestions, Edit this Page button and source locations for the docs. Think this is ready for another round of review.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] thisisnic commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
thisisnic commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r764099344
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,95 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation,
+ try selecting **Components** from the **More** tab in JIRA search
+ and select **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation locally, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
+
+- **C++ documentation** section: ``docs/source/cpp``.
+- **Development** section: ``docs/source/developers``.
+- **Specificatons and protocols** section: ``docs/source/format``.
+- Other language documentation: **C (GLib), Java, JavaScript** and **Python**
+ in folders named by the language, for example: ``docs/source/c_glib``.
+- The documentation for the **R language** is located in the ``r/`` sub-directory.
Review comment:
Yep!
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-983515335
https://issues.apache.org/jira/browse/ARROW-14761
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r763075191
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
Review comment:
```suggestion
When searching for JIRA issue that deals with documentation,
try selecting **Components** from the **More** tab in JIRA search
and select **Documentation** from the list.
```
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation also, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
Review comment:
And actually for C++ it's the same issue
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation also, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
+
+- **C++ documentation** section: ``docs/source/cpp``.
+- **Development** section: ``docs/source/developers``.
+- **Specificatons and protocols** section: ``docs/source/format``.
+- Other language documentation: **C (GLib), Java, JavaScript** and **Python**
+ in folders named by the language, for example: ``docs/source/c_glib``.
+- The documentation for the **R language** is located in the ``r/sub-directory``.
Review comment:
```suggestion
- The documentation for the **R language** is located in the ``r/`` sub-directory.
```
?
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation also, follow detailed instructions
Review comment:
```suggestion
If you wish to build the documentation locally, follow detailed instructions
```
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation also, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
Review comment:
Now you added this list, I think it is relevant to mention "docstrings" for Python as well -> for editing the reference docs, you will need to edit the docstring the pyarrow package itself
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
pitrou commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r761234356
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
Review comment:
Perhaps add something about the "good-first-issue" and "good-second-issue" labels? Example search:
https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20in%20(good-first-issue%2C%20good-second-issue)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r761160452
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
Review comment:
Yes, you are quite right. It's a confusing sentence. Will correct, thanks!
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988479562
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/09424a23af4a4d7fbbe7a741a13bfc62...3367979357364948b806b4effddea141/)
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/6426db36bec7402d9505ee56af064bcc...c63115fda76f476ea15830bd0f9f71f7/)
[Finished :arrow_down:0.27% :arrow_up:0.13%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/f503a06b90dd42e8b840c064c5f40671...3f5a06e01e5e4147b2f2c20470371283/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
pitrou commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r761246363
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
Review comment:
Oh, actually it's done in https://github.com/apache/arrow/pull/11807 . Nevermind.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-984586060
Failing build doesn't seem to be related (RStudio Package Manager error).
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988166427
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Scheduled] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/7ba2b47c222949b690889320364001dd...753eb17d53aa4c55b7449651d092edae/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/1527bb03f0d6487fb39bcecf2a00b3f8...d9733423cae5465bae7bdc4a6874bd77/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/cf3531e76b324d0ebd3dd7c564b7543b...a8a6190d334548188ff9b6875f80f07f/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988479562
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/09424a23af4a4d7fbbe7a741a13bfc62...3367979357364948b806b4effddea141/)
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/6426db36bec7402d9505ee56af064bcc...c63115fda76f476ea15830bd0f9f71f7/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/f503a06b90dd42e8b840c064c5f40671...3f5a06e01e5e4147b2f2c20470371283/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r760961052
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
Review comment:
Yeah, I got bitten by this yesterday! It should be correctly set in the new commit.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-984699838
> * Where are the documentation sources located (i.e. if you are on a page on the online docs, which file to edit?)
That would be great, yes! I will add it into this file, I think it fits nicely.
> * The difference between the prose docs (located in /docs) and the docstrings / doc comments (which also again relates to where to go looking for the source to edit)
This part is maybe a little more complicated, but would definitely need to be added in the existing docs. I can make a separate issue for it?
> For the prose docs, the theme we are using actually has a "edit this page on github" button that can be enabled (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#add-an-edit-this-page-button), that might be interesting to add and show here in combination with the screenshots about how to edit on github (the button itself only brings you to that page on github)
Also something we already talked about! Big +1, will add it to `conf.py` and add the description into this PR.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r763802035
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,95 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation,
+ try selecting **Components** from the **More** tab in JIRA search
+ and select **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation locally, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
+
+- **C++ documentation** section: ``docs/source/cpp``.
+- **Development** section: ``docs/source/developers``.
+- **Specificatons and protocols** section: ``docs/source/format``.
+- Other language documentation: **C (GLib), Java, JavaScript** and **Python**
+ in folders named by the language, for example: ``docs/source/c_glib``.
+- The documentation for the **R language** is located in the ``r/`` sub-directory.
Review comment:
@thisisnic did I get this R part of the documentation source right?
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
pitrou commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r760227845
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
Review comment:
This URL points to a specific issue, we should give the link to the search summary instead, e.g. https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+.. figure:: jira_doc_1.jpeg
Review comment:
Should these figures perhaps be indented so as to be displayed inside the note?
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+.. figure:: jira_doc_1.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+.. figure:: jira_doc_2.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **edit** icon. This
+ will handle making a fork and a pull request for you.
+
+.. figure:: github_edit_1.jpeg
Review comment:
Same suggestion here (put those inside the note).
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
Review comment:
It seems your editor is configured to use tab characters for indentation, can you change it to only insert space characters?
(also, conventionally, the indentation size for `.rst` files is 3 spaces :-))
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-984664966
> Where are the documentation sources located (i.e. if you are on a page on the online docs, which file to edit?)
For the prose docs, the theme we are using actually has a "edit this page on github" button that can be enabled (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#add-an-edit-this-page-button)
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988166427
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/7ba2b47c222949b690889320364001dd...753eb17d53aa4c55b7449651d092edae/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/1527bb03f0d6487fb39bcecf2a00b3f8...d9733423cae5465bae7bdc4a6874bd77/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/cf3531e76b324d0ebd3dd7c564b7543b...a8a6190d334548188ff9b6875f80f07f/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot commented on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot commented on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988479562
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Scheduled] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/09424a23af4a4d7fbbe7a741a13bfc62...3367979357364948b806b4effddea141/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/6426db36bec7402d9505ee56af064bcc...c63115fda76f476ea15830bd0f9f71f7/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/f503a06b90dd42e8b840c064c5f40671...3f5a06e01e5e4147b2f2c20470371283/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r761125632
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
Review comment:
```suggestion
See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
```
(otherwise the link doesn't work for me)
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
Review comment:
This first sentence is a bit hard to follow. Maybe adding a comma after the first line would already help.
Maybe just saying "If you didn't come across something to improve in the documentation itself, you can search for an issue ..." is sufficient?
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche edited a comment on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche edited a comment on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-984664966
> Where are the documentation sources located (i.e. if you are on a page on the online docs, which file to edit?)
For the prose docs, the theme we are using actually has a "edit this page on github" button that can be enabled (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#add-an-edit-this-page-button), that might be interesting to add and show here in combination with the screenshots about how to edit on github (the button itself only brings you to that page on github)
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] AlenkaF commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
AlenkaF commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r763109319
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,79 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation also, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
Review comment:
Ok, will do.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jorisvandenbossche commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jorisvandenbossche commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r763995808
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,95 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+**A great way to contribute to the project is to improve
+documentation.**
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you didn't come across something to improve in the
+documentation itself, you can search for an issue on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation,
+ try selecting **Components** from the **More** tab in JIRA search
+ and select **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+ .. figure:: jira_search_component.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+ .. figure:: jira_search_documentation.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **Edit this page**
+ on the right top corner of the documentations page. This
+ will handle making a fork and a pull request for you.
+
+ .. figure:: edit_page.jpeg
+ :scale: 20 %
+ :alt: click on edit this page
+
+ On the right corner of the file in GitHub click on pen icon.
+
+ .. figure:: github_edit_page.jpeg
+ :scale: 30 %
+ :alt: edit file in GitHub.
+
+ Now you can edit the file in GitHub.
+
+You could also build the entire project, make the change locally on
+your branch and make the PR this way. But it is by no means superior
+to simply editing via GitHub.
+
+If you wish to build the documentation locally, follow detailed instructions
+on :ref:`building-docs`.
+
+Where to find the correct file to change?
+-----------------------------------------
+
+Most of the documentation is located in the ``docs/source`` of the Arrow
+library. Source folder includes:
+
+- **C++ documentation** section: ``docs/source/cpp``.
+- **Development** section: ``docs/source/developers``.
+- **Specificatons and protocols** section: ``docs/source/format``.
+- Other language documentation: **C (GLib), Java, JavaScript** and **Python**
+ in folders named by the language, for example: ``docs/source/c_glib``.
+- The documentation for the **R language** is located in the ``r/`` sub-directory.
+
+ - In the ``R/vignettes`` you can find the **Articles**, for example
+ `Working with Cloud Storage (S3) <https://arrow.apache.org/docs/r/articles/fs.html>`_.
+ - In the ``r/R`` you can edit reference documentation for example
+ in the ``r/R/dataset.R`` you can find the ``docstrings`` for the
+ `open_dataset <https://arrow.apache.org/docs/r/reference/open_dataset.html>`_.
+
+- **Reference documentation**
+
+ To edit `API reference documentation for Python <https://arrow.apache.org/docs/python/api.html>`_,
+ you will need to edit the ``docstring`` of the ``pyarrow`` package itself.
Review comment:
```suggestion
you will need to edit the docstrings of the functions and methods located in the ``pyarrow`` package itself.
```
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] jonkeane closed pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
jonkeane closed pull request #11823:
URL: https://github.com/apache/arrow/pull/11823
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot edited a comment on pull request #11823: ARROW-14761: [Doc] Helping with documentation
Posted by GitBox <gi...@apache.org>.
ursabot edited a comment on pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#issuecomment-988479562
Benchmark runs are scheduled for baseline = 0f502dcf03ff024adb1073a0e973425b54858499 and contender = 784c0a18b97f9535d509d70fbe8a6f822d912eff. 784c0a18b97f9535d509d70fbe8a6f822d912eff is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/09424a23af4a4d7fbbe7a741a13bfc62...3367979357364948b806b4effddea141/)
[Scheduled] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/6426db36bec7402d9505ee56af064bcc...c63115fda76f476ea15830bd0f9f71f7/)
[Scheduled] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/f503a06b90dd42e8b840c064c5f40671...3f5a06e01e5e4147b2f2c20470371283/)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python. Runs only benchmarks with cloud = True
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org