DOCS: update tutorials and style

docs/_static/css/body.css

@@ -0,0 +1,8 @@
+
+.md-grid {
+ max-width: 61rem;
+}
+
+.md-sidebar--secondary {
+ margin-left: 63rem;
+}

docs/_static/css/code.css

@@ -1,25 +1,30 @@
 
-.highlight-py .k {
+.highlight-python .k, .highlight-py .k {
  /*Keyword*/
  color: #3f6ec6;
 }
 
-.highlight-py .kn {
+.highlight-python .c1, .highlight-py .c1 {
+ /*Comment*/
+ color: #808080;
+}
+
+.highlight-python .kn, .highlight-py .kn {
  /*Keyword (import)*/
  color: #3f6ec6;
 }
 
-.highlight-py .nn {
+.highlight-python .nn, .highlight-py .nn {
  /*Module*/
  color: #a846b9;
 }
 
-.highlight-py .nd {
+.highlight-python .nd, .highlight-py .nd {
  /*Decorator*/
  color: #3f6ec6;
 }
 
-.highlight-py .nf {
+.highlight-python .nf, .highlight-py .nf {
  /*Function name*/
  color: #000000;
 }

docs/code/params/return.py

@@ -2,7 +2,6 @@
 
 @app.task()
 def do_first():
-
  return 'Hello World'
 
 @app.task()

docs/code/snippets/pipeline.py

@@ -3,10 +3,8 @@
 
 @app.task(daily)
 def do_first():
-
  return 'Hello World'
 
 @app.task(after_success(do_first))
 def do_second(arg=Return(do_first)):
-
  return 'Hello Python'

docs/conf.py

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

docs/cookbook/controlling_runtime.rst

@@ -1,3 +1,5 @@
+.. _cookbook-control-runtime:
+
 Controlling Runtime
 ===================
 
@@ -99,6 +101,11 @@ You can use the ``Task`` argument:
  def do_on_other(another_task=Task(do_on_self)):
  ...
 
+.. note::
+
+ Read more about task attributes from 
+ :ref:`handbook-task-attrs`.
+
 Or you can use the session:
 
 .. code-block:: python

docs/cookbook/index.rst

@@ -14,6 +14,7 @@ do more specific things.
  conditions
  bigger_applications
  robust_applications
+ task_pipelining
  controlling_runtime
  fastapi
  django

docs/cookbook/task_pipelining.rst

@@ -0,0 +1,42 @@
+Task Pipelining
+===============
+
+Rocketry supports two types of task pipelining:
+
+- Run a task after another task has succeeded or failed
+- Put the return or output value of a task as an input argument to another
+
+Run Task After Another Task
+---------------------------
+
+You can use conditions ``after_...`` to set a task 
+to be run after another task has succeeded or failed. 
+
+Here are some examples:
+
+.. literalinclude:: /code/conds/api/pipe_single.py
+ :language: py
+
+There are also conditions ``after_all_...`` and ``after_any_...``
+if you have a lot of dependent tasks:
+
+.. literalinclude:: /code/conds/api/pipe_multiple.py
+ :language: py
+
+Set Task Output as an Input
+---------------------------
+
+You can also set the output of a task as an input for another
+task. You can use the argument ``Return`` for this purpose:
+
+.. literalinclude:: /code/params/return.py
+ :language: py
+
+Combining Both
+--------------
+
+You can also set a task to be run after another task and 
+also set the output of the latter as an input for the former:
+
+.. literalinclude:: /code/conds/api/pipe_with_return.py
+ :language: py

docs/handbooks/conditions/api/cron.rst

@@ -1,5 +1,5 @@
 
-.. _cron:
+.. _handbook-cond-cron:
 
 Cron Scheduling
 ===============

docs/handbooks/conditions/api/periodical.rst

@@ -1,3 +1,5 @@
+.. _handbook-cond-periodical:
+
 Periodical Execution
 ====================
 
@@ -7,8 +9,8 @@ a given time is reached and the task has not yet run
 at that time, or given time has passed from the previous
 run. Time based scheduling can be divided into two categories:
 
-- Floating periods: Run when given time has passed from previous run
-- Fixed period: Run at given time of day, week etc.
+- Floating period: Run when a given time has passed from previous run
+- Fixed period: Run at a period linked to clock or calendar
 
 Floating Periods
 ----------------
@@ -22,7 +24,7 @@ can be done by:
 
 .. note::
 
- The condition ``every`` is linked running the task
+ The condition ``every`` is linked running the task.
 
 
 Fixed Periods
@@ -38,9 +40,9 @@ agreed fixed time span. Such time spans are:
 
 Running a task every hour is different than running a task
 hourly in Rocketry. The difference is that the former runs
-every time after 60 minutes has passed but the latter every
-full hour. If time is now 07:15, the former will run at 
-08:15 but the latter will run at 08:00.
+when 60 minutes has passed from previous run but the latter 
+runs every full hour. If the current time is 07:45, the 
+former will run at 08:45 but the latter will run at 08:00.
 
 .. literalinclude:: /code/conds/api/periodical.py
  :language: py
@@ -91,3 +93,24 @@ and *starting Friday* means the week is set to start on Friday.
 There are also **time of ...** conditions check if the current time
 is within the given period.
 
+Task independent
+^^^^^^^^^^^^^^^^
+
+The previous examples were linked to a task: the condition is true
+if the current time is in the period and the task has not yet 
+run on that period. There are also purely time-based variants which
+simply checks if the current time is inside the period:
+
+.. literalinclude:: /code/conds/api/time_of.py
+ :language: py
+
+They are especially useful to further constrain the allowed starting
+time with the task dependent time-based conditions, for example:
+
+.. code-block:: python
+
+ from rocketry.conds import weekly, time_of_day
+
+ @app.task(weekly & time_of_day.between("12:00", "18:00"))
+ def do_weekly_in_afternoon():
+ ...

docs/handbooks/conditions/api/pipeline.rst

@@ -1,6 +1,8 @@
 
-Pipelining
-==========
+.. _handbook-cond-pipeline:
+
+Task Pipelines
+==============
 
 There are also conditions related to if another task has 
 runned/succeeded/failed before the task we are setting the

docs/handbooks/conditions/classes/index.rst

@@ -1,3 +1,4 @@
+.. _condition-classes:
 
 Condition Classes
 =================

docs/handbooks/conditions/index.rst

@@ -17,9 +17,9 @@ parentheses.
 
 There are three ways of creating conditions in Rocketry:
 
-- Condition syntax
-- Condition API
-- Condition classes
+- :ref:`Condition syntax <condition-syntax>`
+- :ref:`Condition API (recommended) <condition-api>`
+- :ref:`Condition classes <condition-classes>`
 
 All of the above generate condition instances that 
 can be used as:
@@ -42,6 +42,18 @@ The above returns ``True`` if your current time is between 10:00 (10 AM) and 14:
 Some conditions might rely on a task or the session 
 (passed as ``.observe(task=task, session=session)``).
 
+The built-in conditions can be put to the following categories:
+
+* Time-based conditions
+
+ * Floating time conditions (such as *every 10 seconds*)
+ * Fixed time conditions (such as *daily*, *weekly*)
+
+ * Task and time dependent (true if the current time is in the period and the task has not run on the period)
+ * Time dependent (true if the current time is in given period)
+
+* Task dependent (such as after a task succeeded)
+* Miscellaneous
 
 .. toctree::
  :maxdepth: 3

docs/handbooks/config.rst

@@ -10,25 +10,23 @@ The configurations can be set by:
 
 .. code-block:: python
 
- app = Rocketry(config={
- 'task_execution': 'process',
- 'task_pre_exist': 'raise',
- 'force_status_from_logs': True,
-
- 'silence_task_prerun': False,
- 'silence_task_logging': False,
- 'silence_cond_check': False,
-
- 'max_process_count': 5,
- 'restarting': 'replace',
- 'cycle_sleep': 0.1
+ app = Rocketry(
+ execution="async",
+ task_pre_exist="raise",
+ force_status_from_logs=False,
+ silence_task_prerun=False,
+ silence_task_logging=False,
+ silence_cond_check=False,
+ max_process_count=5,
+ restarting="replace",
+ cycle_sleep=0.1
  })
 
 This can be later accessed via:
 
 .. code-block::
 
- >>> app.session.config.task_execution
+ >>> app.session.config.execution
  'process'
 
 .. note::
@@ -39,7 +37,7 @@ This can be later accessed via:
 Options
 -------
 
-**task_execution**: How tasks are run by default. 
+**execution**: How tasks are run by default. 
 
  Options: 
 

docs/handbooks/task/index.rst

@@ -5,10 +5,38 @@ Task
 In this handbook we go through some technical details of 
 how the tasks works and how to change their behaviour.
 
+.. _handbook-task-attrs:
+
+Attributes
+----------
+
+Here is a list of the most useful task attributes:
+
+**name**: Name of the task.
+
+**execution**: Execution type of the task.
+
+ By default, uses session configuration default.
+
+**multilaunch**: Whether to allow multilaunch.
+
+ If ``True``, the task can be run parallel against 
+ itself. By default, uses the value specified in the 
+ session configurations.
+
+**last_run**: Last datetime the task started.
+
+**last_success**: Last datetime the task succeeded.
+
+**last_fail**: Last datetime the task failed.
+
+**last_terminate**: Last datetime the task terminated.
+
 .. toctree::
  :maxdepth: 2
  :caption: Contents:
 
+ naming
  termination
  execution
  observer

docs/handbooks/task/naming.rst

@@ -0,0 +1,49 @@
+.. _handbook-task-naming:
+
+Task Naming
+===========
+
+Each task should have a unique name within
+the session. If a name is not given to a task,
+the name depends on the task type and it may be 
+derived from the initiation arguments of the task.
+
+For function tasks the name is derived from the 
+name of the function if not specified:
+
+.. code-block:: python
+
+ >>> @app.task()
+ >>> def do_things():
+ >>> ...
+
+ >>> app.session[do_things].name
+ 'do_things'
+
+.. warning::
+
+ As the name must be unique, an error is raised if you try
+ to create multiple tasks from the same function or from 
+ multiple functions with same names without specifying name.
+
+You can pass the name yourself as well:
+
+.. literalinclude:: /code/naming.py
+ :language: py
+
+.. note::
+
+ If you use the decorator (``@app.task()``) to define function
+ task, the decorator returns the function itself due to pickling
+ issues on some platforms. However, the task can be fetched from
+ session using just the function: ``session[do_things]``.
+ There is a special attribute (``__rocketry__``) in 
+ the task function for enabling this.
+
+.. note::
+
+ Task names are used in many conditions and in logging.
+ They are essential in order to find out when a task 
+ started, failed or succeeded. Because of this, it is 
+ not advised to rename a task later unless the logs
+ are cleared as well.