Merge pull request #154 from Miksus/docs/updates

DOCS: Minor documentation improvement

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

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;
+}

docs/conf.py

@@ -81,6 +81,7 @@ def cleanup():
 html_css_files = [
     #'css/types.css',
     #'css/colors.css',
+    "css/code.css",
 ]
 
 html_sidebars = {

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 <https://github.com/Miksus/rocketry>`_.
-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 <https://github.com/sponsors/Miksus>`_
+- `Report an issue (bug, feature request etc.) <https://github.com/Miksus/rocketry/issues>`_
+- `Do code a change <https://github.com/Miksus/rocketry/pulls>`_
+- `Join the discussion <https://github.com/Miksus/rocketry/discussions>`_
+
+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
 
     <iframe src="https://github.com/sponsors/Miksus/button" title="Sponsor Miksus" height="35" width="116" style="border: 0;"></iframe>
 
-The project is developed with passion but writing high-quality code is hard and time consuming.
-All support is welcome.  
+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 <https://github.com/Miksus/rocketry/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=ENH>`_.
+
+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 <https://github.com/Miksus/rocketry/discussions>`_.
+
+Found a bug?
+------------
+
+If you found a bug,
+`please report it as a bug <https://github.com/Miksus/rocketry/issues/new?assignees=&labels=bug&template=bug_report.md&title=BUG>`_.
+
+Unclear documentation?
+----------------------
+
+If you found an issue with the documentation,
+`please report it <https://github.com/Miksus/rocketry/issues/new?assignees=&labels=documentation&template=documentation_improvement.md&title=DOCS>`_.
+
+Want to do a code contribution?
+------------------------------- 
+
+Good place to start is to look for open issues 
+`from issue tracker <https://github.com/Miksus/rocketry/issues>`_. 
+
+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.

docs/handbooks/task/index.rst

@@ -11,3 +11,4 @@ how the tasks works and how to change their behaviour.
 
    termination
    execution
+   observer

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()

docs/handbooks/task/termination.rst

@@ -9,12 +9,47 @@ 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 <handbook-execution>`.
 
+.. 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
 -------