From 6a85ffc915078e233759553eb30f408db4d13755 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrianna=20Pi=C5=84ska?= Date: Mon, 17 Feb 2014 15:28:07 +0200 Subject: [PATCH 1/3] Added 1.0 branch for first released version of the notes From 6bd54e5f34ab14fbc94a1d7e0b465afc33c21fd3 Mon Sep 17 00:00:00 2001 From: Simon Cross Date: Sat, 17 Jun 2023 16:14:22 +0200 Subject: [PATCH 2/3] Add readthedocs configuration file. --- .readthedocs.yaml | 22 ++++++++++++++++++++++ requirements.pip | 2 +- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..2d04131 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: python_notes/conf.py + +# We recommend specifying your dependencies to enable reproducible builds: +# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: requirements.pip diff --git a/requirements.pip b/requirements.pip index 317d163..3480017 100644 --- a/requirements.pip +++ b/requirements.pip @@ -1,2 +1,2 @@ Sphinx -blockdiag \ No newline at end of file +blockdiag From 658b66bb6f9bbc8ea47e6cd17caa88a72539bf02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrianna=20Pi=C5=84ska?= Date: Sat, 28 Oct 2023 18:08:09 +0200 Subject: [PATCH 3/3] attempting to fix build --- .gitignore | 1 + doc/TODO.txt | 5 - doc/rough-notes.rst | 221 --------------------- lib/sphinxcontrib/__init__.py | 0 lib/sphinxcontrib/blockdiag.py | 337 --------------------------------- requirements.pip | 2 +- 6 files changed, 2 insertions(+), 564 deletions(-) create mode 100644 .gitignore delete mode 100644 doc/TODO.txt delete mode 100644 doc/rough-notes.rst delete mode 100644 lib/sphinxcontrib/__init__.py delete mode 100755 lib/sphinxcontrib/blockdiag.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..766ec13 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +python_notes/_build diff --git a/doc/TODO.txt b/doc/TODO.txt deleted file mode 100644 index 00e2b5e..0000000 --- a/doc/TODO.txt +++ /dev/null @@ -1,5 +0,0 @@ -GLOBAL SEARCH AND REPLACE - -* replace "you" with "we" almost everywhere in earlier chapters - done up to collections; check everything -* put term definitions in italics in earlier chapters -* add hyperlinks between exercises and answers and whenever something is referenced? diff --git a/doc/rough-notes.rst b/doc/rough-notes.rst deleted file mode 100644 index 1e55e1b..0000000 --- a/doc/rough-notes.rst +++ /dev/null @@ -1,221 +0,0 @@ -.. From http://www.cs.uct.ac.za/mit_notes/Java/Latest/html/single-html.html - - -Chapter 1: Introduction -======================= - -* What is a Computer: - * update hardware introduction - -* Programming a Computer: - * mention dynamic languages and interpreters somewhere - * mention JITs somewhere - * convert Java Programming Language to Python - * convert Developing a Java Program to Python - -* Types of Computers: - * update section - -* History of Computers: - * add what happened after the 70s - -* Programming Languages: - * add static vs dynamic languages - * add strongly vs weakly typed languages - * explain where Python fits in - - -Chapter 2: Java Basics -====================== - -* Introduction - * mention Python 3 and Python 2. - -* Essentials of a Java Program - * skeleton, keywords, identifiers, __main__, indentation, print, - string formating, mention files - -* Primitive Types - * simple types -- integers, floats, boolean, strings - * delay discussion of static and class variables until OO section - -* Variables of Primitive Types and Strings - * assignment is just labelling in Python - -* Constants - * replace with discussion of mutable vs immutable - * mention constants in other languages. - -* Input - * input() - * translate scanner example - -* Type conversion - * translate discussion to Python - -* Compiling Java Programs - * Running Python programs - * Select appropriate Python IDE and translate wizard example - -* Differences between Python 2 and 3 - * raw_input() - * print - * unicode vs bytes - -* translate exercises - - -Chapter 3: Selection Control Statements -======================================= - -* Selection: if statement - * == vs "is" - * translate examples - -* More on the if statement - * nested if - * dangling else not applicable - * if ladders -> elif - -* Boolean Operators and Expression - * and, or and not operators - * translate operator precedence - * translate De Morgan's laws - * remove char type discussion - * Aha! Replace this with booleans! - -* The switch Statement - * mention Python doesn't have one - * discuss dictionary-based dispatch - -* Conditional Operators Shortcut - * "x if y else z" - -* Errors - * SyntaxError - * discussion of Python's exception hierarchy - * explain where Python fits in - * static error checking (pyflakes, pep8) - -* Testing and Debugging Programs - * Add discussion of unit vs functional vs integrated tests - - -Chapter 4: Loop Control Statements -================================== - -* The for statement - * discuss differences between Python and C/Java/C++ for loops. - -* The while statement - -* Add section of looping pitfalls - * not editing mutable sequences while you iterate over them. - * infinite loops - -* Do-while loops - * Replace with mention of do-while in other languages and while True - equivalent. - -* The break and continue statements - -* Add a section for list comprehensions - * Potential replacement for some simple for loops. - - -Chapter 5: Using Classes -======================== - -* Merge with chapter 6 probably. - -Chapter 6: Writing Your Own Classes -=================================== - -* Translate to Python -* classmethod, staticmethod, __init__, magic methods (__str__, __eq__, ...) -* Translate section on packaging classes to discussion on packages, modules, - etc. (probably move further up). - - -Chapter 7: Arrays -================= - -* Discussions of arrays in other languages. -* Discussion of lists in Python. -* Discussion of tuples. -* Maybe move to a more generic section about sequences. -* Mention how to do 2D arrays in Python. -* Do we need a discussion / mention of Numpy? - -Chapter 8: Sorting and Searching Arrays -======================================= - -* Translate algorithms -* Using all the equivalent Python statements in the standard library -* How much of the algorithm stuff should be kept? -* Timsort. :) - -Chapter 9: Object Orientated Approach to Programming -==================================================== - -* Mostly translating examples. -* Mention NotImplementedError. -* Mention Mix-ins. -* Are metaclasses too advanced to mention? -* Class decorators? - -Chapter 10: Exceptions -====================== - -* Translate to Python - -Chapters 11-12: Array List and Linked List -========================================== - -* Replace with discussion of all the cool Python collections: - * lists, dicts, sets -* Maybe move further up the discussion -* Should the linked list algorithm be replaced with something more relevant? - * Maybe a tree or graph implementation? - - -Chapter 13: Better Collections: Using Interfaces, OO, and Generics -================================================================== - -* Rewrite. -* Mention collections somewhere. -* Mention zope.interfaces somewhere. -* Generics mostly irrelevant. - -Chapter 14: Introduction to GUI Programming with Swing -====================================================== - -* translate to Tcl/Tk. -* mention other toolkits. -* replace with introduction to web programming? Django? Flask? - -Broader Issues -============== - -* docstrings need to be mentioned somewhere -- currently in packaging/testing chapter -* file I/O -- in Python Basics? Chop up Python Basics some more? - -* add more detail about scope within classes to the class chapter, where it will make more sense. - -* Add chapter on functions (before chapter 5 on classes) - * Decorators! -* Parameter passing -* Writing procedural code -* Writing functional code - * Nested functions - -* classes: a chapter or section about overriding str, comparison methods, iter, exceptions, etc.. - -* Split chapters more sensibly for Python - * group sequence types -* Discussion of .pyc files. -* Do we want something about C extensions? -* Do we want something about regular expressions? -* Mention version control? - -* one or two chapters about useful standard libraries: datetime, regex, csv parsing, os and sys (how system-agnostic can we make it?) including writing scripts and command-line parameters diff --git a/lib/sphinxcontrib/__init__.py b/lib/sphinxcontrib/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/lib/sphinxcontrib/blockdiag.py b/lib/sphinxcontrib/blockdiag.py deleted file mode 100755 index d9b0534..0000000 --- a/lib/sphinxcontrib/blockdiag.py +++ /dev/null @@ -1,337 +0,0 @@ -# -*- coding: utf-8 -*- -""" - blockdiag.sphinx_ext - ~~~~~~~~~~~~~~~~~~~~ - - Allow blockdiag-formatted diagrams to be included in Sphinx-generated - documents inline. - - :copyright: Copyright 2010 by Takeshi Komiya. - :license: BSDL. -""" - -import io -import os -import re -import posixpath -import traceback -from collections import namedtuple -try: - from hashlib import sha1 as sha -except ImportError: - from sha import sha - -from docutils import nodes -from sphinx.errors import SphinxError -from sphinx.util.osutil import ensuredir - -import blockdiag_sphinxhelper as blockdiag -u = blockdiag.utils.compat.u - - -class BlockdiagError(SphinxError): - category = 'Blockdiag error' - - -class Blockdiag(blockdiag.utils.rst.directives.BlockdiagDirective): - def run(self): - try: - return super(Blockdiag, self).run() - except blockdiag.core.parser.ParseException as e: - if self.content: - msg = '[%s] ParseError: %s\n%s' % (self.name, e, "\n".join(self.content)) - else: - msg = '[%s] ParseError: %s\n%r' % (self.name, e, self.arguments[0]) - - reporter = self.state.document.reporter - return [reporter.warning(msg, line=self.lineno)] - - def node2image(self, node, diagram): - return node - - -def get_image_filename(self, code, format, options, prefix='blockdiag'): - """ - Get path of output file. - """ - if format.upper() not in ('PNG', 'PDF', 'SVG'): - raise BlockdiagError('blockdiag error:\nunknown format: %s\n' % format) - - if format.upper() == 'PDF': - try: - __import__("reportlab") - except ImportError: - msg = 'blockdiag error:\n' + \ - 'could not output PDF format; Install reportlab\n' - raise BlockdiagError(msg) - - hashkey = (code + str(options)).encode('utf-8') - fname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), format.lower()) - if hasattr(self.builder, 'imgpath'): - # HTML - relfn = posixpath.join(self.builder.imgpath, fname) - outfn = os.path.join(self.builder.outdir, '_images', fname) - else: - # LaTeX - relfn = fname - outfn = os.path.join(self.builder.outdir, fname) - - if os.path.isfile(outfn): - return relfn, outfn - - ensuredir(os.path.dirname(outfn)) - - return relfn, outfn - - -def get_fontmap(self): - FontMap = blockdiag.utils.fontmap.FontMap - - try: - fontmappath = self.builder.config.blockdiag_fontmap - fontmap = FontMap(fontmappath) - except: - attrname = '_blockdiag_fontmap_warned' - if not hasattr(self.builder, attrname): - msg = ('blockdiag cannot load "%s" as fontmap file, ' - 'check the blockdiag_fontmap setting' % fontmappath) - self.builder.warn(msg) - setattr(self.builder, attrname, True) - - fontmap = FontMap(None) - - try: - fontpath = self.builder.config.blockdiag_fontpath - if isinstance(fontpath, blockdiag.utils.compat.string_types): - fontpath = [fontpath] - - if fontpath: - config = namedtuple('Config', 'font')(fontpath) - _fontpath = blockdiag.utils.bootstrap.detectfont(config) - fontmap.set_default_font(_fontpath) - except: - attrname = '_blockdiag_fontpath_warned' - if not hasattr(self.builder, attrname): - msg = ('blockdiag cannot load "%s" as truetype font, ' - 'check the blockdiag_fontpath setting' % fontpath) - self.builder.warn(msg) - setattr(self.builder, attrname, True) - - return fontmap - - -def get_anchor(self, refid, fromdocname): - for docname in self.builder.env.found_docs: - doctree = self.builder.env.get_doctree(docname) - for target in doctree.traverse(nodes.Targetable): - if target.attributes.get('refid') == refid: - targetfile = self.builder.get_relative_uri(fromdocname, docname) - return targetfile + "#" + refid - - -def resolve_reference(self, href, options): - if href is None: - return - pattern = re.compile(u("^:ref:`(.+?)`"), re.UNICODE) - matched = pattern.search(href) - if matched: - return get_anchor(self, matched.group(1), options.get('current_docname', '')) - else: - return href - - -def create_blockdiag(self, code, format, filename, options, prefix): - """ - Render blockdiag code into a PNG output file. - """ - draw = None - fontmap = get_fontmap(self) - try: - tree = blockdiag.core.parser.parse_string(code) - diagram = blockdiag.core.builder.ScreenNodeBuilder.build(tree) - for node in diagram.traverse_nodes(): - if node.href: - node.href = resolve_reference(self, node.href, options) - - antialias = self.builder.config.blockdiag_antialias - draw = blockdiag.core.drawer.DiagramDraw(format, diagram, filename, - fontmap=fontmap, antialias=antialias) - - except Exception as e: - if self.builder.config.blockdiag_debug: - traceback.print_exc() - - raise BlockdiagError('blockdiag error:\n%s\n' % e) - - return draw - - -def make_svgtag(self, image, relfn, trelfn, outfn, - alt, thumb_size, image_size): - svgtag_format = """%s - """ - - code = io.open(outfn, 'r', encoding='utf-8-sig').read() - - return (svgtag_format % - (alt, image_size[0], image_size[1], code)) - - -def make_imgtag(self, image, relfn, trelfn, outfn, - alt, thumb_size, image_size): - result = "" - - clickable_map = [] - for n in image.nodes: - if n.href: - cell = image.metrics.cell(n) - clickable_map.append((cell, n.href)) - - if clickable_map: - imgtag_format = '%s' % relfn) - result += (imgtag_format % - (trelfn, alt, thumb_size[0], thumb_size[1])) - result += ('') - else: - result += (imgtag_format % - (relfn, alt, image_size[0], image_size[1])) - - if clickable_map: - result += ('' % id(image)) - rect_format = '' - for m in clickable_map: - x1 = m[0].x1 - y1 = m[0].y1 - x2 = m[0].x2 - y2 = m[0].y2 - result += (rect_format % (x1, y1, x2, y2, m[1])) - - result += ('') - - return result - - -def render_dot_html(self, node, code, options, prefix='blockdiag', - imgcls=None, alt=None): - trelfn = None - thumb_size = None - try: - format = self.builder.config.blockdiag_html_image_format - relfn, outfn = get_image_filename(self, code, format, options, prefix) - - options['current_docname'] = self.builder.current_docname - image = create_blockdiag(self, code, format, outfn, options, prefix) - - if not os.path.isfile(outfn): - image.draw() - image.save() - - # generate thumbnails - image_size = image.pagesize() - if 'maxwidth' in options and options['maxwidth'] < image_size[0]: - thumb_prefix = prefix + '_thumb' - trelfn, toutfn = get_image_filename(self, code, format, - options, thumb_prefix) - - ratio = float(options['maxwidth']) / image_size[0] - thumb_size = (options['maxwidth'], image_size[1] * ratio) - if not os.path.isfile(toutfn): - image.filename = toutfn - image.save(thumb_size) - - except UnicodeEncodeError: - msg = ("blockdiag error: UnicodeEncodeError caught " - "(check your font settings)") - self.builder.warn(msg) - raise nodes.SkipNode - except BlockdiagError as exc: - self.builder.warn('dot code %r: ' % code + str(exc)) - raise nodes.SkipNode - - self.body.append(self.starttag(node, 'p', CLASS='blockdiag')) - if relfn is None: - self.body.append(self.encode(code)) - else: - if alt is None: - alt = node.get('alt', self.encode(code).strip()) - - if format.upper() == 'SVG': - tagfunc = make_svgtag - else: - tagfunc = make_imgtag - - self.body.append(tagfunc(self, image, relfn, trelfn, outfn, alt, - thumb_size, image_size)) - - self.body.append('

\n') - raise nodes.SkipNode - - -def html_visit_blockdiag(self, node): - render_dot_html(self, node, node['code'], node['options']) - - -def render_dot_latex(self, node, code, options, prefix='blockdiag'): - try: - format = self.builder.config.blockdiag_tex_image_format - fname, outfn = get_image_filename(self, code, format, options, prefix) - - image = create_blockdiag(self, code, format, outfn, options, prefix) - if not os.path.isfile(outfn): - image.draw() - image.save() - - except BlockdiagError as exc: - self.builder.warn('dot code %r: ' % code + str(exc)) - raise nodes.SkipNode - - if fname is not None: - self.body.append('\\par\\includegraphics{%s}\\par' % fname) - raise nodes.SkipNode - - -def latex_visit_blockdiag(self, node): - render_dot_latex(self, node, node['code'], node['options']) - - -def on_doctree_resolved(self, doctree, docname): - if self.builder.format in ('html', 'latex'): - return - - for node in doctree.traverse(blockdiag.utils.rst.nodes.blockdiag): - code = node['code'] - prefix = 'blockdiag' - format = 'PNG' - options = node['options'] - relfn, outfn = get_image_filename(self, code, format, options, prefix) - - image = create_blockdiag(self, code, format, outfn, options, prefix) - if not os.path.isfile(outfn): - image.draw() - image.save() - - candidates = {'image/png': relfn} - image = nodes.image(uri=outfn, candidates=candidates) - node.parent.replace(node, image) - - -def setup(app): - app.add_node(blockdiag.utils.rst.nodes.blockdiag, - html=(html_visit_blockdiag, None), - latex=(latex_visit_blockdiag, None)) - app.add_directive('blockdiag', Blockdiag) - app.add_config_value('blockdiag_fontpath', None, 'html') - app.add_config_value('blockdiag_fontmap', None, 'html') - app.add_config_value('blockdiag_antialias', False, 'html') - app.add_config_value('blockdiag_debug', False, 'html') - app.add_config_value('blockdiag_html_image_format', 'PNG', 'html') - app.add_config_value('blockdiag_tex_image_format', 'PNG', 'html') - app.connect("doctree-resolved", on_doctree_resolved) diff --git a/requirements.pip b/requirements.pip index 3480017..1a34f22 100644 --- a/requirements.pip +++ b/requirements.pip @@ -1,2 +1,2 @@ Sphinx -blockdiag +sphinxcontrib-blockdiag