changeset fd57d9653a2f in modules/project:default
details: https://hg.tryton.org/modules/project?cmd=changeset&node=fd57d9653a2f
description:
Improve project module documentation
issue10092
review341341002
diffstat:
doc/conf.py | 61 +++++++++++++++++++++++++++++++++
doc/design.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 36 +++---------------
doc/usage.rst | 28 +++++++++++++++
setup.py | 7 ++-
5 files changed, 206 insertions(+), 31 deletions(-)
diffs (277 lines):
diff -r cccab2e1da5b -r fd57d9653a2f doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Tue Aug 31 13:33:26 2021 +0100
@@ -0,0 +1,61 @@
+# This file is part of Tryton. The COPYRIGHT file at the top level of
+# this repository contains the full copyright notices and license terms.
+
+modules_url = 'https://docs.tryton.org/projects/modules-{module}/en/{series}/'
+trytond_url = 'https://docs.tryton.org/projects/server/en/{series}/'
+
+
+def get_info():
+ import configparser
+ import os
+ import subprocess
+ import sys
+
+ module_dir = os.path.dirname(os.path.dirname(__file__))
+
+ config = configparser.ConfigParser()
+ config.read_file(open(os.path.join(module_dir, 'tryton.cfg')))
+ info = dict(config.items('tryton'))
+
+ result = subprocess.run(
+ [sys.executable, 'setup.py', '--name'],
+ stdout=subprocess.PIPE, check=True, cwd=module_dir)
+ info['name'] = result.stdout.decode('utf-8').strip()
+
+ result = subprocess.run(
+ [sys.executable, 'setup.py', '--version'],
+ stdout=subprocess.PIPE, check=True, cwd=module_dir)
+ version = result.stdout.decode('utf-8').strip()
+ if 'dev' in version:
+ info['series'] = 'latest'
+ else:
+ info['series'] = '.'.join(version.split('.', 2)[:2])
+
+ for key in {'depends', 'extras_depend'}:
+ info[key] = info.get(key, '').strip().splitlines()
+ info['modules'] = set(info['depends'] + info['extras_depend'])
+ info['modules'] -= {'ir', 'res'}
+
+ return info
+
+
+info = get_info()
+
+master_doc = 'index'
+project = info['name']
+release = version = info['series']
+default_role = 'ref'
+highlight_language = 'none'
+extensions = [
+ 'sphinx.ext.intersphinx',
+ ]
+intersphinx_mapping = {
+ 'trytond': (trytond_url.format(series=version), None),
+ }
+intersphinx_mapping.update({
+ m: (modules_url.format(
+ module=m.replace('_', '-'), series=version), None)
+ for m in info['modules']
+ })
+
+del get_info, info, modules_url, trytond_url
diff -r cccab2e1da5b -r fd57d9653a2f doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Tue Aug 31 13:33:26 2021 +0100
@@ -0,0 +1,105 @@
+******
+Design
+******
+
+The *Project Module* introduces some new concepts and extends some existing
+concepts:
+
+.. _model-project.work:
+
+Work Effort
+===========
+
+The *Work Effort* concept is used to represent work that must be done for
+projects, or parts of projects.
+
+Each *Work Effort* is described by a name and a type, and there is space
+for additional comments to be added when required.
+
+The estimated time and effort needed for a the work is recorded, and it is
+also possible to track the actual time and effort required.
+
+If timesheets are selected to be used, then the time spent on the work can
+be recorded by `Employees <company:model-company.employee>` by creating
+`Timesheet Lines <timesheet:model-timesheet.line>` with the right
+`Timesheet Works <timesheet:model-timesheet.work>`.
+The *Timesheet Works* for the *Work Efforts* are automatically created and
+deleted as needed.
+
+The current progress of a project's work and its
+`Work Status <model-project.work.status>` is also recorded.
+
+A project's work can be structured by giving work efforts a parent and some
+children, if required.
+
+Each *Work Effort* has a type.
+Once a work effort has been created it can be changed to a different type
+if its scope, or the amount of work required, changes.
+
+.. seealso::
+
+ Work efforts can be found by opening the main menu item:
+
+ |Project --> Configuration --> Works Efforts|__
+
+ .. |Project --> Configuration --> Works Efforts| replace::
:menuselection:`Project --> Configuration --> Works Efforts`
+ __ https://demo.tryton.org/model/project.work
+
+.. _concept-project.work.project:
+
+Project
+-------
+
+A *Project* is a type of *Work Effort* that is used for larger and more
+complex work.
+
+It can have a `Party <party:model-party.party>` and
+`Party Address <party:model-party.address>`.
+These are used to record who the project is for.
+
+.. seealso::
+
+ A list of projects can be found using the main menu item:
+
+ |Project --> Projects --> Projects|__
+
+ .. |Project --> Projects --> Projects| replace:: :menuselection:`Project
--> Projects --> Projects`
+ __
https://demo.tryton.org/model/project.work;name="Projects"&domain=[["type"%2C"%3D"%2C"project";]]
+
+.. _concept-project.work.task:
+
+Task
+----
+
+A *Task* is a type of *Work Effort* that is used for smaller pieces of work.
+
+.. seealso::
+
+ A list of tasks can be found using the main menu item:
+
+ |Project --> Projects --> Tasks|__
+
+ .. |Project --> Projects --> Tasks| replace:: :menuselection:`Project
--> Projects --> Tasks`
+ __
https://demo.tryton.org/model/project.work;name="Tasks"&domain=[["type"%2C"%3D"%2C"task";]]
+
+.. _model-project.work.status:
+
+Work Status
+===========
+
+The *Work Status* concept is used to define the different stages that a
+project's `Work <model-project.work>` goes through.
+
+Each status can be used with one, or more, types of work.
+
+The progress set on the work status defines the minimum amount of progress
+needed for work to have that status.
+
+.. seealso::
+
+ The available *Work Statuses* are found using the main menu item:
+
+ |Project --> Configuration --> Work Status|__
+
+ .. |Project --> Configuration --> Work Status| replace::
:menuselection:`Project --> Configuration --> Work Status`
+ __ https://demo.tryton.org/model/project.work
diff -r cccab2e1da5b -r fd57d9653a2f doc/index.rst
--- a/doc/index.rst Sun Jul 04 17:54:47 2021 +0200
+++ b/doc/index.rst Tue Aug 31 13:33:26 2021 +0100
@@ -1,34 +1,12 @@
+##############
Project Module
##############
-The Project module provides the concepts of project and task and the
-basis for simple project management.
-
-Work Effort
-***********
-
-The Work Effort model is used for creating both projects and tasks. This allows
-for instance to transform a task into a project if it gets bigger and need to
-be split. The following fields are defined on the model:
+The *Project Module* contains the basic concepts that are needed for managing
+simple projects.
-- Name: The name of the Project/Task.
-- Type: Can be *Project* or *Task*.
-- Status: The current status of the work.
-- Parent and Children: Define the tree structure of projects and tasks.
-- Party and Party Address: The optional party (and the contact address) for
- which the project is made. Available on projects.
-- Timesheet, start and end: Allow to enter timesheet for this work.
-- Effort: The estimated effort of a task.
-- Total Effort: Available on projects. Gives the total effort of the sub-tasks
- (I.E. tasks of the project and tasks of the sub-projects) of the current
- project.
-- Progress: The progression on the task.
-- Total Progress: Gives the total of progress of the sub-tasks.
-- Comment: A description.
+.. toctree::
+ :maxdepth: 2
-
-Work Status
-***********
-
-The Work Status defines the possible status of projects and tasks. A minimal
-progress can be defined to enforce on works in this status.
+ usage
+ design
diff -r cccab2e1da5b -r fd57d9653a2f doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Tue Aug 31 13:33:26 2021 +0100
@@ -0,0 +1,28 @@
+*****
+Usage
+*****
+
+You can find things related to projects under the [:menuselection:`Projects`]
+main menu item.
+
+.. _Setting up projects and tasks:
+
+Setting up projects and tasks
+=============================
+
+In Tryton both `Projects <concept-project.work.project>` and
+`Tasks <concept-project.work.task>` are just types of
+`Work Efforts <model-project.work>`.
+
+In many cases projects and tasks can be used interchangeably.
+However, it is often best practice to use projects for larger more complex
+jobs and then break these down into sub tasks for the smaller individual
+parts of each project.
+To allow you to do this you can give each project or task a parent, and
+any number of children.
+
+.. tip::
+
+ With your projects structured like this any time and effort expended on a
+ project or task will then also be included as part of its parent's total
+ effort.
diff -r cccab2e1da5b -r fd57d9653a2f setup.py
--- a/setup.py Sun Jul 04 17:54:47 2021 +0200
+++ b/setup.py Tue Aug 31 13:33:26 2021 +0100
@@ -10,9 +10,12 @@
def read(fname):
- return io.open(
+ content = io.open(
os.path.join(os.path.dirname(__file__), fname),
'r', encoding='utf-8').read()
+ content = re.sub(
+ r'(?m)^\.\. toctree::\r?\n((^$|^\s.*$)\r?\n)*', '', content)
+ return content
def get_require_version(name):
@@ -80,7 +83,7 @@
download_url=download_url,
project_urls={
"Bug Tracker": 'https://bugs.tryton.org/',
- "Documentation": 'https://docs.tryton.org/',
+ "Documentation": 'https://docs.tryton.org/projects/modules-project/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/project',
},
