From 34e40ebfb5de5e1f618cd7deda95ffcc9bda8300 Mon Sep 17 00:00:00 2001 From: poolitzer <25934244+Poolitzer@users.noreply.github.com> Date: Tue, 20 Apr 2021 13:17:17 +0200 Subject: [PATCH 1/6] feat: add docs about docs --- .github/CONTRIBUTING.rst | 69 ++++++++++++++++++++++---------- .github/pull_request_template.md | 1 + 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 7aaf44360cf..1f89a20c564 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -73,27 +73,7 @@ Here's how to make a one-off code change. - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram.utils.helpers.typing``. - - Document your code. This project uses `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies: - - .. code-block:: bash - - $ pip install -r docs/requirements-docs.txt - - then run the following from the PTB root directory: - - .. code-block:: bash - - $ make -C docs html - - or, if you don't have ``make`` available (e.g. on Windows): - - .. code-block:: bash - - $ sphinx-build docs/source docs/build/html - - Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser. - - - Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed. + - Document your code. This step is pretty important to us, so it has its own section below. :ref:`Documenting` - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. @@ -151,7 +131,7 @@ Here's how to make a one-off code change. 5. **Address review comments until all reviewers give LGTM ('looks good to me').** - - When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways: + - When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways: - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)". @@ -186,6 +166,49 @@ Here's how to make a one-off code change. 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``! +Documenting +----------- + +The documentation of this project is separated in two sections: User facing and dev facing. + +User facing docs are hosted at `RTD`_. They are the main way the users of our library are supposed to get information about the objects. They don't care about the technical side, they just want to know +what they have to pass to make it work, what it actually does. You can/should provide examples for non obvious cases (like the Filter module), and notes/warnings. + +Dev facing, on the other side, is for the devs/maintainers of this project. This is a big part of the documentation we have neglected thus far, but not anymore! These +doc strings don't have a separate documentation site they generate, instead, they document the actual code. + +User facing documentation +========================= +We use `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies: + + .. code-block:: bash + + $ pip install -r docs/requirements-docs.txt + + then run the following from the PTB root directory: + + .. code-block:: bash + + $ make -C docs html + + or, if you don't have ``make`` available (e.g. on Windows): + + .. code-block:: bash + + $ sphinx-build docs/source docs/build/html + + Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser. + +- Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed. + +Dev facing documentation +======================== +We adhere to the `CSI`_ standard. Again, remember, this documentation is not fully implemented in the project, yet. We still ask you to add it to your code changes and this way, we will slowly document the whole project this way. +The idea behind this is to make it very easy for you/a random maintainer or even a totally foreign person to drop anywhere into the code and more or less immediately understand what a particular line does. This will make it easier +for new or old devs who are out of the loop to make relevant changes if said lines don't do what they are supposed to. Even though implementing this will mean a lot of comments, we still believe in it being a very meaningful addition to our project. + + + Style commandments ------------------ @@ -252,4 +275,6 @@ break the API classes. For example: .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html .. _`Black`: https://black.readthedocs.io/en/stable/index.html .. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html +.. _`RTD`: https://python-telegram-bot.readthedocs.io/ .. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes +.. _`CSI`: https://standards.mousepawmedia.com/csi.html diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index bd33a19cbd7..3ade5116561 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,6 +6,7 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to - [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes) - [ ] Created new or adapted existing unit tests +- [ ] Documented code dev facing - [ ] Added myself alphabetically to `AUTHORS.rst` (optional) From a0af264941d4ffdee3f5cd705196765f99adafba Mon Sep 17 00:00:00 2001 From: poolitzer <25934244+Poolitzer@users.noreply.github.com> Date: Tue, 20 Apr 2021 13:24:36 +0200 Subject: [PATCH 2/6] fix: improve looks --- .github/CONTRIBUTING.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 1f89a20c564..365a9aca072 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -73,7 +73,7 @@ Here's how to make a one-off code change. - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram.utils.helpers.typing``. - - Document your code. This step is pretty important to us, so it has its own section below. :ref:`Documenting` + - Document your code. This step is pretty important to us, so it has its own section below: _`Documenting`. - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. @@ -167,7 +167,7 @@ Here's how to make a one-off code change. 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``! Documenting ------------ +=========== The documentation of this project is separated in two sections: User facing and dev facing. @@ -178,31 +178,31 @@ Dev facing, on the other side, is for the devs/maintainers of this project. This doc strings don't have a separate documentation site they generate, instead, they document the actual code. User facing documentation -========================= +------------------------- We use `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies: - .. code-block:: bash +.. code-block:: bash - $ pip install -r docs/requirements-docs.txt +$ pip install -r docs/requirements-docs.txt - then run the following from the PTB root directory: +then run the following from the PTB root directory: - .. code-block:: bash +.. code-block:: bash - $ make -C docs html +$ make -C docs html - or, if you don't have ``make`` available (e.g. on Windows): +or, if you don't have ``make`` available (e.g. on Windows): - .. code-block:: bash +.. code-block:: bash - $ sphinx-build docs/source docs/build/html +$ sphinx-build docs/source docs/build/html - Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser. +Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser. - Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed. Dev facing documentation -======================== +------------------------ We adhere to the `CSI`_ standard. Again, remember, this documentation is not fully implemented in the project, yet. We still ask you to add it to your code changes and this way, we will slowly document the whole project this way. The idea behind this is to make it very easy for you/a random maintainer or even a totally foreign person to drop anywhere into the code and more or less immediately understand what a particular line does. This will make it easier for new or old devs who are out of the loop to make relevant changes if said lines don't do what they are supposed to. Even though implementing this will mean a lot of comments, we still believe in it being a very meaningful addition to our project. From 74370ccc8d2c9e1ded4b44db645638cbb21758e4 Mon Sep 17 00:00:00 2001 From: poolitzer <25934244+Poolitzer@users.noreply.github.com> Date: Tue, 20 Apr 2021 13:28:23 +0200 Subject: [PATCH 3/6] fix: make link work --- .github/CONTRIBUTING.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 365a9aca072..c69d0b38c56 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -73,7 +73,7 @@ Here's how to make a one-off code change. - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram.utils.helpers.typing``. - - Document your code. This step is pretty important to us, so it has its own section below: _`Documenting`. + - Document your code. This step is pretty important to us, so it has its own `section`_. - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. @@ -278,3 +278,4 @@ break the API classes. For example: .. _`RTD`: https://python-telegram-bot.readthedocs.io/ .. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes .. _`CSI`: https://standards.mousepawmedia.com/csi.html +.. _`section`: documenting From be3d8444326cf46edbe945f8938f606ed793642c Mon Sep 17 00:00:00 2001 From: poolitzer <25934244+Poolitzer@users.noreply.github.com> Date: Tue, 20 Apr 2021 13:29:53 +0200 Subject: [PATCH 4/6] fix: this looks better --- .github/CONTRIBUTING.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index c69d0b38c56..ee9caefa216 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -278,4 +278,4 @@ break the API classes. For example: .. _`RTD`: https://python-telegram-bot.readthedocs.io/ .. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes .. _`CSI`: https://standards.mousepawmedia.com/csi.html -.. _`section`: documenting +.. _`section`: #documenting From f7b2a7fa0c23f6c4115c549b371c97dc49fae7e9 Mon Sep 17 00:00:00 2001 From: Poolitzer Date: Sun, 1 Aug 2021 12:16:29 +0200 Subject: [PATCH 5/6] Improved markdown, updated link --- .github/CONTRIBUTING.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index ee9caefa216..35910f36805 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -183,19 +183,19 @@ We use `sphinx`_ to generate static HTML docs. To build them, first make sure yo .. code-block:: bash -$ pip install -r docs/requirements-docs.txt + $ pip install -r docs/requirements-docs.txt then run the following from the PTB root directory: .. code-block:: bash -$ make -C docs html + $ make -C docs html or, if you don't have ``make`` available (e.g. on Windows): .. code-block:: bash -$ sphinx-build docs/source docs/build/html + $ sphinx-build docs/source docs/build/html Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser. @@ -277,5 +277,5 @@ break the API classes. For example: .. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html .. _`RTD`: https://python-telegram-bot.readthedocs.io/ .. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes -.. _`CSI`: https://standards.mousepawmedia.com/csi.html +.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html .. _`section`: #documenting From 1e14b8b79a016a196c6adb8ceaaac5b5e3552c24 Mon Sep 17 00:00:00 2001 From: Poolitzer Date: Wed, 11 Aug 2021 11:56:39 +0200 Subject: [PATCH 6/6] Less justifying Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> --- .github/CONTRIBUTING.rst | 8 ++++---- .github/pull_request_template.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 35910f36805..22e08a75f7d 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -171,10 +171,10 @@ Documenting The documentation of this project is separated in two sections: User facing and dev facing. -User facing docs are hosted at `RTD`_. They are the main way the users of our library are supposed to get information about the objects. They don't care about the technical side, they just want to know +User facing docs are hosted at `RTD`_. They are the main way the users of our library are supposed to get information about the objects. They don't care about the internals, they just want to know what they have to pass to make it work, what it actually does. You can/should provide examples for non obvious cases (like the Filter module), and notes/warnings. -Dev facing, on the other side, is for the devs/maintainers of this project. This is a big part of the documentation we have neglected thus far, but not anymore! These +Dev facing, on the other side, is for the devs/maintainers of this project. These doc strings don't have a separate documentation site they generate, instead, they document the actual code. User facing documentation @@ -203,9 +203,9 @@ Once the process terminates, you can view the built documentation by opening ``d Dev facing documentation ------------------------ -We adhere to the `CSI`_ standard. Again, remember, this documentation is not fully implemented in the project, yet. We still ask you to add it to your code changes and this way, we will slowly document the whole project this way. +We adhere to the `CSI`_ standard. This documentation is not fully implemented in the project, yet, but new code changes should comply with the `CSI` standard. The idea behind this is to make it very easy for you/a random maintainer or even a totally foreign person to drop anywhere into the code and more or less immediately understand what a particular line does. This will make it easier -for new or old devs who are out of the loop to make relevant changes if said lines don't do what they are supposed to. Even though implementing this will mean a lot of comments, we still believe in it being a very meaningful addition to our project. +for new to make relevant changes if said lines don't do what they are supposed to. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3ade5116561..09f5fdacef7 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,7 +6,7 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to - [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes) - [ ] Created new or adapted existing unit tests -- [ ] Documented code dev facing +- [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html) - [ ] Added myself alphabetically to `AUTHORS.rst` (optional)