... | ... |
@@ -8,13 +8,7 @@ |
8 | 8 |
/dist |
9 | 9 |
/doc/build |
10 | 10 |
/doc/source/reference/generated/ |
11 |
-/doc/source/code/include/*.py |
|
12 |
-/doc/source/code/figure/*.png |
|
13 |
-/doc/source/code/figure/*.pdf |
|
14 |
-/doc/source/code/figure/.*_flag |
|
15 |
-/doc/source/code/figure/[a-zA-Z]*.py |
|
16 |
-/doc/source/code/figure/*.txt |
|
17 |
-/doc/source/code/download/ |
|
11 |
+/doc/source/figure/*.pdf |
|
18 | 12 |
/build.conf |
19 | 13 |
/kwant.egg-info/ |
20 | 14 |
/MANIFEST.in |
This completes 9fdd41e8483043d4.
Christoph Groth authored on 26/10/2017 11:01:41I assume that most people encounter the tutorial example scripts by
reading the documentation, and not by viewing the tutorial subdirectory
of a checked-out Kwant source.
That's the motivation for moving all the manipulations of tutorial
scripts from setup.py to doc/Makefile. Previously, a successful 'make
html' would require a preceding execution of 'setup.py build_tut'. Now,
a simple 'make html' is enough.
While at it, I reorganized where the example scripts and their outputs
are stored. Everything is now in 'doc/source/code' with its three
subdirectories 'download' (to be shown to readers), 'include' (with
include markers), and 'figure' (figure generation & figures). This
organization is clearer and also makes the generation of figures
separate from the tutorial.
... | ... |
@@ -8,13 +8,14 @@ |
8 | 8 |
/build |
9 | 9 |
/dist |
10 | 10 |
/doc/build |
11 |
-/doc/source/tutorial/*.py |
|
12 | 11 |
/doc/source/reference/generated/ |
13 |
-/doc/source/images/*.png |
|
14 |
-/doc/source/images/*.pdf |
|
15 |
-/doc/source/images/.*_flag |
|
16 |
-/doc/source/images/[a-zA-Z]*.py |
|
17 |
-/doc/source/images/*.txt |
|
12 |
+/doc/source/code/include/*.py |
|
13 |
+/doc/source/code/figure/*.png |
|
14 |
+/doc/source/code/figure/*.pdf |
|
15 |
+/doc/source/code/figure/.*_flag |
|
16 |
+/doc/source/code/figure/[a-zA-Z]*.py |
|
17 |
+/doc/source/code/figure/*.txt |
|
18 |
+/doc/source/code/download/ |
|
18 | 19 |
/build.conf |
19 | 20 |
/kwant.egg-info/ |
20 | 21 |
/MANIFEST.in |
The basic idea remains the same, but should work much better now. The
difference is that images/example.py.diff is now a patch with complete
context and becomes the authoritative source for both the visible flavor
of an example as well as for its figure-generating variant. Both
tutorial/example.py and images/example.py are extracted from this file
by 'make html'. Thanks to the complete context the diffs are quite
readable and may be modified directly.
Alternatively, one may also modify the generated scripts. When
tutorial/example.py has been modified, it will be patched and saved as
images/example.py. The patching is done using the tool 'wiggle' that
works much better than 'patch'. If a conflict occurs, conflict markers
are added to the output file and its dated back to the dawn of time
(i.e. 1970) in order to mark the conflicts as not yet resolved. After
resolving, 'make html' is simply run again.
Upon a successful execution of the figure-generating script the diff
gets recreated automatically, 'generate-diffs' no longer exists.
The file kwant/_static_version.py is no longer written upon every
invocation of setup.py. Instead, a file kwant/_kwant_version.py is
injected into source and binary distributions.
The static version in kwant/_kwant_version.py now takes precedence
before any version from git. This makes the --no-git option to setup.py
no longer necessary, since the existence of kwant/_kwant_version.py has
the same role. The motivation behind this change is to allow keeping
Kwant distributions in git repositories that have a different layout
from the canonical Kwant git repository. This is useful for example for
packaging.
The name of the static version file was changed to avoid problems with
stale files.
The code should be easier to understand. Configuration through a site.cfg file
is supported.