diff --git a/InvenTree/build/api.py b/InvenTree/build/api.py index 41d46bab49..c9e756839f 100644 --- a/InvenTree/build/api.py +++ b/InvenTree/build/api.py @@ -1,3 +1,7 @@ +""" +Provides a JSON API for the Build app +""" + # -*- coding: utf-8 -*- from __future__ import unicode_literals @@ -11,7 +15,14 @@ from .models import Build from .serializers import BuildSerializer -class BuildList(generics.ListAPIView): +class BuildList(generics.ListCreateAPIView): + """ API endpoint for accessing a list of Build objects. + + Provides two methods: + + - GET: Return list of objects (with filters) + - POST: Create a new Build object + """ queryset = Build.objects.all() serializer_class = BuildSerializer diff --git a/InvenTree/build/forms.py b/InvenTree/build/forms.py index 1775b5c3b5..6254f0745c 100644 --- a/InvenTree/build/forms.py +++ b/InvenTree/build/forms.py @@ -1,3 +1,7 @@ +""" +Django Forms for interacting with Build objects +""" + # -*- coding: utf-8 -*- from __future__ import unicode_literals @@ -7,6 +11,8 @@ from .models import Build class EditBuildForm(HelperForm): + """ Form for editing a Build object. + """ class Meta: model = Build diff --git a/InvenTree/build/models.py b/InvenTree/build/models.py index c72aa5209b..3d4feef93a 100644 --- a/InvenTree/build/models.py +++ b/InvenTree/build/models.py @@ -1,3 +1,9 @@ +""" +Build models + +Defines the database models for part Builds +""" + # -*- coding: utf-8 -*- from __future__ import unicode_literals @@ -9,60 +15,61 @@ from django.core.validators import MinValueValidator class Build(models.Model): - """ A Build object organises the creation of new parts from the component parts - It uses the part BOM to generate new parts. - Parts are then taken from stock + """ A Build object organises the creation of new parts from the component parts. """ def get_absolute_url(self): return reverse('build-detail', kwargs={'pk': self.id}) + part = models.ForeignKey('part.Part', on_delete=models.CASCADE, + related_name='builds', + limit_choices_to={'buildable': True}, + ) + """ A reference to the part being built - only parts marked as 'buildable' may be selected """ + + #: Brief title describing the build + title = models.CharField(max_length=100, help_text='Brief description of the build') + + #: Number of output parts to build + quantity = models.PositiveIntegerField(default=1, + validators=[MinValueValidator(1)], + help_text='Number of parts to build') + # Build status codes PENDING = 10 # Build is pending / active HOLDING = 20 # Build is currently being held CANCELLED = 30 # Build was cancelled COMPLETE = 40 # Build is complete + #: Build status codes BUILD_STATUS_CODES = {PENDING: _("Pending"), HOLDING: _("Holding"), CANCELLED: _("Cancelled"), COMPLETE: _("Complete"), } - batch = models.CharField(max_length=100, blank=True, null=True, - help_text='Batch code for this build output') - - # Status of the build + #: Status of the build (ref BUILD_STATUS_CODES) status = models.PositiveIntegerField(default=PENDING, choices=BUILD_STATUS_CODES.items(), validators=[MinValueValidator(0)]) - # Date the build model was 'created' + #: Batch number for the build (optional) + batch = models.CharField(max_length=100, blank=True, null=True, + help_text='Batch code for this build output') + + + #: Date the build model was 'created' creation_date = models.DateField(auto_now=True, editable=False) - # Date the build was 'completed' + #: Date the build was 'completed' (and parts removed from stock) completion_date = models.DateField(null=True, blank=True) - # Brief build title - title = models.CharField(max_length=100, help_text='Brief description of the build') - - # A reference to the part being built - # Only 'buildable' parts can be selected - part = models.ForeignKey('part.Part', on_delete=models.CASCADE, - related_name='builds', - limit_choices_to={'buildable': True}, - ) - - # How many parts to build? - quantity = models.PositiveIntegerField(default=1, - validators=[MinValueValidator(1)], - help_text='Number of parts to build') - - # Notes can be attached to each build output + #: Notes attached to each build output notes = models.TextField(blank=True) @property def required_parts(self): + """ Returns a dict of parts required to build this part (BOM) """ parts = [] for item in self.part.bom_items.all(): @@ -77,8 +84,7 @@ class Build(models.Model): @property def can_build(self): - """ Return true if there are enough parts to supply build - """ + """ Return true if there are enough parts to supply build """ for item in self.required_parts: if item['part'].total_stock < item['quantity']: @@ -88,10 +94,10 @@ class Build(models.Model): @property def is_active(self): - """ Is this build active? - An active build is either: - - Pending - - Holding + """ Is this build active? An active build is either: + + - PENDING + - HOLDING """ return self.status in [ @@ -101,4 +107,5 @@ class Build(models.Model): @property def is_complete(self): + """ Returns True if the build status is COMPLETE """ return self.status == self.COMPLETE diff --git a/InvenTree/build/serializers.py b/InvenTree/build/serializers.py index ac36fd5b41..92534ef816 100644 --- a/InvenTree/build/serializers.py +++ b/InvenTree/build/serializers.py @@ -1,3 +1,7 @@ +""" +Provides JSON serializers for Build API +""" + # -*- coding: utf-8 -*- from __future__ import unicode_literals @@ -7,6 +11,7 @@ from .models import Build class BuildSerializer(serializers.ModelSerializer): + """ Serializes a Build object """ url = serializers.CharField(source='get_absolute_url', read_only=True) status_text = serializers.CharField(source='get_status_display', read_only=True) diff --git a/InvenTree/build/urls.py b/InvenTree/build/urls.py index a8e4435e24..fea3b6596c 100644 --- a/InvenTree/build/urls.py +++ b/InvenTree/build/urls.py @@ -1,3 +1,7 @@ +""" +URL lookup for Build app +""" + from django.conf.urls import url, include from . import views diff --git a/InvenTree/build/views.py b/InvenTree/build/views.py index f3f7bd79f3..756566e694 100644 --- a/InvenTree/build/views.py +++ b/InvenTree/build/views.py @@ -1,3 +1,7 @@ +""" +Provides Django views for interacting with Build objects +""" + # -*- coding: utf-8 -*- from __future__ import unicode_literals @@ -13,11 +17,14 @@ from InvenTree.views import AjaxView, AjaxUpdateView, AjaxCreateView class BuildIndex(ListView): + """ View for displaying list of Builds + """ model = Build template_name = 'build/index.html' context_object_name = 'builds' def get_queryset(self): + """ Return all Build objects (order by date, newest first) """ return Build.objects.order_by('status', '-completion_date') def get_context_data(self, **kwargs): @@ -35,6 +42,9 @@ class BuildIndex(ListView): class BuildCancel(AjaxView): + """ View to cancel a Build. + Provides a cancellation information dialog + """ model = Build template_name = 'build/cancel.html' ajax_form_title = 'Cancel Build' @@ -42,6 +52,7 @@ class BuildCancel(AjaxView): fields = [] def post(self, request, *args, **kwargs): + """ Handle POST request. Mark the build status as CANCELLED """ build = get_object_or_404(Build, pk=self.kwargs['pk']) @@ -51,24 +62,28 @@ class BuildCancel(AjaxView): return self.renderJsonResponse(request, None) def get_data(self): + """ Provide JSON context data. """ return { 'info': 'Build was cancelled' } class BuildDetail(DetailView): + """ Detail view of a single Build object. """ model = Build template_name = 'build/detail.html' context_object_name = 'build' class BuildAllocate(DetailView): + """ View for allocating parts to a Build """ model = Build context_object_name = 'build' template_name = 'build/allocate.html' class BuildCreate(AjaxCreateView): + """ View to create a new Build object """ model = Build context_object_name = 'build' form_class = EditBuildForm @@ -76,6 +91,11 @@ class BuildCreate(AjaxCreateView): ajax_template_name = 'modal_form.html' def get_initial(self): + """ Get initial parameters for Build creation. + + If 'part' is specified in the GET query, initialize the Build with the specified Part + """ + initials = super(BuildCreate, self).get_initial().copy() part_id = self.request.GET.get('part', None) @@ -92,6 +112,8 @@ class BuildCreate(AjaxCreateView): class BuildUpdate(AjaxUpdateView): + """ View for editing a Build object """ + model = Build form_class = EditBuildForm context_object_name = 'build' diff --git a/InvenTree/keygen.py b/InvenTree/keygen.py index 02909b0d79..c96df22794 100644 --- a/InvenTree/keygen.py +++ b/InvenTree/keygen.py @@ -1,7 +1,5 @@ """ -Module keygen -============= -This module generates a Django SECRET_KEY file to be used by manage.py +Generates a Django SECRET_KEY file to be used by manage.py """ import random @@ -15,11 +13,13 @@ KEY_DIR = os.path.dirname(os.path.realpath(__file__)) def generate_key(length=50): - """ - Generate a random string + """ Generate a random string - :param length: Number of characters in returned string (default=50) - :returns: Randomized secret key string + Args: + length: Number of characters in returned string (default = 50) + + Returns: + Randomized secret key string """ options = string.digits + string.ascii_letters + string.punctuation diff --git a/docs/conf.py b/docs/conf.py index 78bcb74673..3b21b24458 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,9 +28,13 @@ copyright = '2019, InvenTree' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'autoapi.extension' + 'sphinx.ext.napoleon', + 'autoapi.extension', ] +napoleon_google_docstring = True +napoleon_numpy_docstring = False + autoapi_dirs = [ '../InvenTree', ] @@ -44,7 +48,10 @@ autoapi_type = 'python' autoapi_ignore = [ '*migrations*', '**/test*.py', - '**/manage.py' + '**/manage.py', + '**/apps.py', + '**/admin.py', + '**/templates/', ] # Add any paths that contain templates here, relative to this directory.