From 4c02e7232379fbc78cae699ff91a21387a708cea Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sun, 20 Nov 2022 13:42:05 +0200 Subject: [PATCH 1/6] docs: nicer code blocks --- docs/_static/css/code.css | 25 +++++++++++++++++++++++++ docs/conf.py | 1 + 2 files changed, 26 insertions(+) create mode 100644 docs/_static/css/code.css diff --git a/docs/_static/css/code.css b/docs/_static/css/code.css new file mode 100644 index 00000000..ced6d41b --- /dev/null +++ b/docs/_static/css/code.css @@ -0,0 +1,25 @@ + +.highlight-py .k { + /*Keyword*/ + color: #3f6ec6; +} + +.highlight-py .kn { + /*Keyword (import)*/ + color: #3f6ec6; +} + +.highlight-py .nn { + /*Module*/ + color: #a846b9; +} + +.highlight-py .nd { + /*Decorator*/ + color: #3f6ec6; +} + +.highlight-py .nf { + /*Function name*/ + color: #000000; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index a9b1742d..da9107b2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -81,6 +81,7 @@ def cleanup(): html_css_files = [ #'css/types.css', #'css/colors.css', + "css/code.css", ] html_sidebars = { From 7c3a783fd355ac90e91ca8b97a28eeec64078e20 Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sun, 20 Nov 2022 13:42:49 +0200 Subject: [PATCH 2/6] docs: add contributor to contributors --- Contributors.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Contributors.md b/Contributors.md index 18a36947..ee8a1d20 100644 --- a/Contributors.md +++ b/Contributors.md @@ -2,3 +2,4 @@ Mikael Koli - creator of Rocketry Mark Mayo - fixes and clean up of repo with python 3 updates, pylint issues +bogdan - Django cookbook \ No newline at end of file From afffbbd224063237d7a53484511708a90f53629b Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sat, 26 Nov 2022 01:12:30 +0200 Subject: [PATCH 3/6] docs: improved termination.rst --- docs/handbooks/task/termination.rst | 34 +++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/handbooks/task/termination.rst b/docs/handbooks/task/termination.rst index bbee27a0..1cbce7e7 100644 --- a/docs/handbooks/task/termination.rst +++ b/docs/handbooks/task/termination.rst @@ -9,12 +9,46 @@ following are met: - Task's ``end_cond`` is true - Scheduler is immediately shutting down +This section discusses these ways to terminate tasks. + .. warning:: Only ``async``, ``thread`` and ``process`` tasks can be terminated. Read more about the execution methods: `execution method handbook `. +.. warning:: + + If you use threaded execution, you should periodically check + the termination flag status and raise termination exception + if it is set in order to correctly handle the termination: + + .. code-block:: python + + from rocketry.args import TerminationFlag + from rocketry.exc import TaskTerminationException + + @app.task(execution="thread") + def do_thread(flag=TerminationFlag()): + while True: + ... # Do something + if flag.is_set(): + raise TaskTerminationException() + +.. warning:: + + If you use async execution, you should release the execution + in order to make it possible for the scheduler to terminate it: + + .. code-block:: python + + import asyncio + + @app.task(execution="async") + async def do_async(): + ... # Do things + await asyncio.sleep(0) + ... # Do more Timeout ------- From c63541e281febbb4e485af41af6eeb172fb7e678 Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sat, 26 Nov 2022 01:14:28 +0200 Subject: [PATCH 4/6] docs: add observer task section --- docs/handbooks/task/index.rst | 1 + docs/handbooks/task/observer.rst | 42 ++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/handbooks/task/observer.rst diff --git a/docs/handbooks/task/index.rst b/docs/handbooks/task/index.rst index 852e436e..0df99038 100644 --- a/docs/handbooks/task/index.rst +++ b/docs/handbooks/task/index.rst @@ -11,3 +11,4 @@ how the tasks works and how to change their behaviour. termination execution + observer \ No newline at end of file diff --git a/docs/handbooks/task/observer.rst b/docs/handbooks/task/observer.rst new file mode 100644 index 00000000..669d4907 --- /dev/null +++ b/docs/handbooks/task/observer.rst @@ -0,0 +1,42 @@ +Observer Task +============= + +Observer tasks are tasks that are running constantly +on the side. Observer tasks can be used for: + +- Monitoring the system +- Hosting user interface or polling user inputs +- Polling events or updates + +Observer tasks are characterized as tasks that +are not expected to complete and don't have +timeouts. Unlike other tasks, observer tasks are +always immediately terminated when shutting down +the scheduler regardless of the shutdown settings. + +To set a task as an observer task, set ``permanent`` +as ``True``: + +.. code-block:: python + + @app.task(permanent=True) + def monitor(): + while True: + ... + +.. note:: + + If you use threaded execution for observer task, + you should periodically check the termination flag + status: + + .. code-block:: python + + from rocketry.args import TerminationFlag + from rocketry.exc import TaskTerminationException + + @app.task(permanent=True) + def monitor(flag=TerminationFlag()): + while not flag.is_set(): + ... + raise TaskTerminationException() \ No newline at end of file From ab9a70232a4c7f4852eb2e2011a0abd8f84919af Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sat, 26 Nov 2022 20:23:36 +0200 Subject: [PATCH 5/6] docs: fix missing line break --- docs/handbooks/task/termination.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/handbooks/task/termination.rst b/docs/handbooks/task/termination.rst index 1cbce7e7..49c01c34 100644 --- a/docs/handbooks/task/termination.rst +++ b/docs/handbooks/task/termination.rst @@ -49,6 +49,7 @@ This section discusses these ways to terminate tasks. ... # Do things await asyncio.sleep(0) ... # Do more + Timeout ------- From 600b560e365aeb1258ae38459bfceb26eabe2a78 Mon Sep 17 00:00:00 2001 From: Mikael Koli Date: Sat, 26 Nov 2022 20:24:06 +0200 Subject: [PATCH 6/6] docs: improved contributing.rst --- docs/contributing.rst | 106 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 6 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 071d94c1..3a75a061 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -2,16 +2,110 @@ Contributing ============ -All help is welcome. If you found a bug or have ideas or suggestions, -please create an issue in `Rocketry Github page `_. -Also pull requests are welcome. +All help is welcome. There are several ways to contribute: -If you represent a company or project that has benefited from Rocketry, consider sponsoring the free +- `Sponsoring `_ +- `Report an issue (bug, feature request etc.) `_ +- `Do code a change `_ +- `Join the discussion `_ + +Sponsoring +---------- + +If you represent a company and your project has benefited from Rocketry, consider sponsoring the free open-source project to ensure further development and maintenance: .. raw:: html -The project is developed with passion but writing high-quality code is hard and time consuming. -All support is welcome. \ No newline at end of file +The project is developed with passion but creating high-quality code is hard and time consuming. +All support is welcome. + +Have an Idea? +------------- + +If you have a concrete idea of a feature you wish Rocketry had, +feel free to open `a feature request `_. + +If you have ideas about broader or more abstract features or would like to discuss about the future directions of the framework, +feel free to open a discussion about it to `Rocketry's discussion board `_. + +Found a bug? +------------ + +If you found a bug, +`please report it as a bug `_. + +Unclear documentation? +---------------------- + +If you found an issue with the documentation, +`please report it `_. + +Want to do a code contribution? +------------------------------- + +Good place to start is to look for open issues +`from issue tracker `_. + +If you found a problem and the fix is simple, you don't have to create an issue +for it. Complex changes require an issue. + +Development Guidelines +^^^^^^^^^^^^^^^^^^^^^^ + +How to do code contribution: + +1. Create an issue (you don't need an issue if it's simple) +2. Fork and clone the project +3. Do your changes +4. Run the tests locally or check the documentation +5. Create a pull request + +There are some criteria that new code must pass: + +- Well tested (with unit tests) +- Well documented +- No breaking changes (unless strictly necessary) +- Follows best practices and standard naming conventions + +Improving documentation +^^^^^^^^^^^^^^^^^^^^^^^ + +If you made a change to documentation, please build them by: +``` +pip install tox +tox -e docs +``` +Then go to the ``/docs/_build/html/index.html`` and check the +change looks visually good. + +Improving code +^^^^^^^^^^^^^^ + +To do code changes: + +1. Open an issue (unless trivial) +2. Fork and clone the repository +3. Do the changes +4. Run the tests (see below) +5. Do a pull request + +To run the tests, you can use tox: + +``` +pip install tox +tox +``` + +To ensure your pull request gets approved: + +- Create unit tests that demonstrates the bug it fixed or the feature implemented +- Write documentation (unless it's a bug fix) +- Ensure standard behaviour raises no warnings +- Ensure the code follows best practices and fits to the project + +Don't feel overwhelmed with these, there are automatic pipelines to ensure code quality +and your code can be updated after the pull request. Rocketry's maintainers understand +that you are using your free time to contribute on free open-source software.