diff --git a/notes/Makefile b/notes/Makefile new file mode 100644 index 000000000..c04392b09 --- /dev/null +++ b/notes/Makefile @@ -0,0 +1,8 @@ +all: notes.html + +%.html: %.rst html4css1.css custom.css + rst2html --stylesheet html4css1.css,custom.css $< $@ + +%.pdf: %.rst + rst2pdf $< + diff --git a/notes/custom.css b/notes/custom.css new file mode 100644 index 000000000..152d372df --- /dev/null +++ b/notes/custom.css @@ -0,0 +1,26 @@ +/* +:Author: Henrik Levkowetz +:Contact: henrik@levkowetz.com +:Copyright: This stylesheet has been placed in the public domain. + +Stylesheet for use with Docutils. +*/ + +/* Your customizations go here. For example: */ + +.document { + margin: 0.2em 0.4em; + width: 50em; +} +/* Undo some of the settings above, for fully css compliant browsers. */ +/* The qualification of the elements hide this from less capable browsers. */ +div[class=document] { + width: auto; + max-width: 50em; /* 58em = 128ex in the design browser */ +} + +cite { + display: block; + width: 100%; + text-align: right; +} diff --git a/notes/html4css1.css b/notes/html4css1.css new file mode 100644 index 000000000..816050614 --- /dev/null +++ b/notes/html4css1.css @@ -0,0 +1,303 @@ +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math { + margin-left: 2em ; + margin-right: 2em } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } diff --git a/notes/notes.html b/notes/notes.html new file mode 100644 index 000000000..85980a5b1 --- /dev/null +++ b/notes/notes.html @@ -0,0 +1,407 @@ + + + + + + +Datatracker development notes + + + + +
+

Datatracker development notes

+ +
+

Introduction

+

This file should be ordered with the most recent entries at the top.

+

Before March 2014, notes on choices made and paths taken, to the extent they +have been written, has been sent by email and thus don't exist as a collection +in one place.

+

With my recent investigations of code analysis tools, I thought it might be +a good idea to start collecting these in one place for the project.

+
+Henrik <henrik@levkowetz.com>, 23 Mar 2014
+
+
+

Code Analysis Tools

+
+

PyFlakes

+

Pyflakes has proved robust and easy to work with, and has shown no false +positives in the messages provided. It has been included in the form of a +standalone management command, as well as a test suite test.

+
+
+

Vulture

+

Vulture has been a disappointment. Given that the purpose of using it was to +discover dead code, it was necessary to extend the Vulture class to also parse +and process variables in template files, as these are points where reference +back to object methods and object attributes can be made.

+

Unfortunately, once this extension was in place, it turned out that the amount +of remaining false positives was unreasonably large, because Vulture fails to +understand that the declarative style of Django models (from +django.models.Model) and admin classes (from django.contrib.admin.ModelAdmin) +doesn't in fact constitute unused class attributes.

+

Finally, it turns out that Vulture is really simpleminded about what +constitutes usage. It has one set of global lists for used functions, used +attributes, and used variables; any instance of overlapping function, method, +variable, or attribute naming across modules will result in one instance of +use in one module masking lack of usage in all other modules.

+

At the moment, it looks like it might be a better way forward to see if +PyFlakes could be extended with some dead code capability, than to continue to +pound on what seems to be a broken framework in Vulture.

+
+
+

PyLint

+

PyLint has been excluded from futher consideration because it doesn't only +parse the code, it also executes it, which comes with both a speed penalty and +the possibility of triggering unwanted side effects of doing an analysis run.

+
+
+

PyChecker

+

PyChecker turned out to require much more fiddling than PyFlakes in order to +do the right thing, but once it was made to run on the datatracker code, and +ignore the django code, it didn't report anything that PyFlakes hadn't already +caught.

+
+Henrik <henrik@levkowetz.com>, 23 Mar 2014
+
+
+
+ + diff --git a/notes/notes.rst b/notes/notes.rst new file mode 100644 index 000000000..d0c4844c2 --- /dev/null +++ b/notes/notes.rst @@ -0,0 +1,73 @@ +============================================================================== + Datatracker Development Notes +============================================================================== + +Introduction +============ + +This file should be ordered with the most recent entries at the top. + +Before March 2014, notes on choices made and paths taken, to the extent they +have been written, has been sent by email and thus don't exist as a collection +in one place. + +With my recent investigations of code analysis tools, I thought it might be +a good idea to start collecting these in one place for the project. + + `Henrik , 23 Mar 2014` + + +Code Analysis Tools +=================== + +PyFlakes +-------- + +Pyflakes has proved robust and easy to work with, and has shown no false +positives in the messages provided. It has been included in the form of a +standalone management command, as well as a test suite test. + + +Vulture +------- + +Vulture has been a disappointment. Given that the purpose of using it was to +discover dead code, it was necessary to extend the Vulture class to also parse +and process variables in template files, as these are points where reference +back to object methods and object attributes can be made. + +Unfortunately, once this extension was in place, it turned out that the amount +of remaining false positives was unreasonably large, because Vulture fails to +understand that the declarative style of Django models (from +django.models.Model) and admin classes (from django.contrib.admin.ModelAdmin) +doesn't in fact constitute unused class attributes. + +Finally, it turns out that Vulture is really simpleminded about what +constitutes usage. It has one set of global lists for used functions, used +attributes, and used variables; any instance of overlapping function, method, +variable, or attribute naming across modules will result in one instance of +use in one module masking lack of usage in all other modules. + +At the moment, it looks like it might be a better way forward to see if +PyFlakes could be extended with some dead code capability, than to continue to +pound on what seems to be a broken framework in Vulture. + + +PyLint +------ + +PyLint has been excluded from futher consideration because it doesn't only +parse the code, it also executes it, which comes with both a speed penalty and +the possibility of triggering unwanted side effects of doing an analysis run. + + +PyChecker +--------- + +PyChecker turned out to require much more fiddling than PyFlakes in order to +do the right thing, but once it was made to run on the datatracker code, and +ignore the django code, it didn't report anything that PyFlakes hadn't already +caught. + + + `Henrik , 23 Mar 2014` diff --git a/notes/notes.txt b/notes/notes.txt new file mode 100644 index 000000000..3bebca299 --- /dev/null +++ b/notes/notes.txt @@ -0,0 +1,69 @@ +============================================================================== + Datatracker development notes +============================================================================== + +Introduction +------------ + +This file is ordered with the most recent dates at the top. + +23 Mar 2014 +........... + +Earlier, notes on choices made and paths taken, to the extent they have been +written, has been sent by email and thus don't exist as a collection in one +place. + +With my recent investigations of code analysis tools, I thought it might be +a good idea to start collecting these in one place for the project. + + +PyFlakes +-------- + +Pyflakes has proved robust and easy to work with, and has shown no false +positives in the messages provided. It has been included in the form of a +standalone management command, as well as a test suite test. + + +Vulture +------- + +Vulture has been a disappointment. Given that the purpose of using it was to +discover dead code, it was necessary to extend the Vulture class to also parse +and process variables in template files, as these are points where reference +back to object methods and object attributes can be made. + +Unfortunately, once this extension was in place, it turned out that the amount +of remaining false positives was unreasonably large, because Vulture fails to +understand that the declarative style of Django models (from +django.models.Model) and admin classes (from django.contrib.admin.ModelAdmin) +doesn't in fact constitute unused class attributes. + +Finally, it turns out that Vulture is really simpleminded about what +constitutes usage. It has one set of global lists for used functions, used +attributes, and used variables; any instance of overlapping function, method, +variable, or attribute naming across modules will result in one instance of +use in one module masking lack of usage in all other modules. + +At the moment, it looks like it might be a better way forward to see if +PyFlakes could be extended with some dead code capability, than to continue to +pound on what seems to be a broken framework in Vulture. + + +PyLint +------ + +PyLint has been excluded from futher consideration because it doesn't only +parse the code, it also executes it, which comes with both a speed penalty and +the possibility of triggering unwanted side effects of doing an analysis run. + + +PyChecker +--------- + +PyChecker turned out to require much more fiddling than PyFlakes in order to +do the right thing, but once it was made to run on the datatracker code, and +ignore the django code, it didn't report anything that PyFlakes hadn't already +caught. +