|
4 | 4 |
|
5 | 5 | * Overview |
6 | 6 |
|
7 | | -The ~docs/~ sub package provides support for various forms of |
8 | | -documentation provided by the ~wire-cell-toolkit~ repository. |
9 | | -It integrates with the ~wire-cell-docs~ repository. |
| 7 | +The ~docs/~ sub package provides support for various forms of documentation provided by the ~wire-cell-toolkit~ repository. |
10 | 8 |
|
11 | | -* Source |
| 9 | +* Documentation source |
12 | 10 |
|
13 | | -Most of the documentation source file is written in [[https://orgmode.org/][org markup]]. Each |
14 | | -file is expected to produce an associated export file (eg ~foo.org~ |
15 | | -produces ~foo.html~). That is, authors should avoid use of ~#+include:~ |
16 | | -directives to aggregate files. In some special cases, documentation |
17 | | -source files may be aggregated for the purpose of producing a |
18 | | -monolithic export. Particular care is needed so that links resolve |
19 | | -properly. |
| 11 | +The documentation text source is written in plain text following [[https://orgmode.org/][org markup]]. |
20 | 12 |
|
21 | | -* README |
| 13 | +** README |
22 | 14 |
|
23 | | -At [[file:../README.org][top level]] and in every sub package in the WCT repo there is a |
24 | | -~README.org~ file. These files provide entry points into the |
25 | | -documentation for their context (top or sub package). They should be |
26 | | -brief and delegate to other documents under the sibling directory |
27 | | -~docs/~. |
| 15 | +At [[file:../README.org][top level]] and in every sub package in the WCT repo there is a ~README.org~ file. These files should provide a brief explanation of their context and then delegate details to other documents under the sibling directory ~docs/~. |
28 | 16 |
|
29 | | -Every ~README.org~ file must use the ~setup-readme.org~ setup file. For |
30 | | -those in a sub-package they must start with lines like: |
| 17 | +Every ~README.org~ file should start with lines like: |
31 | 18 |
|
32 | 19 | #+begin_example |
33 | 20 | ,#+title: Wire-Cell Toolkit <Package> |
34 | 21 | ,#+include: ../docs/include-readme.org |
35 | 22 | #+end_example |
36 | 23 |
|
37 | | -* Topic files |
| 24 | +This will allow the file to be consistently integrated with publishing (see below). |
38 | 25 |
|
39 | | -The WCT /topics/ documents provide the bulk of the WCT in-source |
40 | | -documentation. They are placed under ~<pkg>/docs/~ and written to |
41 | | -assume in-place export from that location (eg, for linking to or |
42 | | -including source from other files). A topic document must use the |
43 | | -~setup-topic.org~ setup file by using initial lines such as: |
| 26 | +** Topic files |
| 27 | + |
| 28 | +A /topic/ file holds some detailed documentation on some aspect. It should be placed under ~<pkg>/docs/<topic>.org~. |
| 29 | + |
| 30 | +Every /topic/ file should start with lines like: |
44 | 31 |
|
45 | 32 | #+begin_example |
46 | 33 | ,#+title: Wire-Cell Toolkit Topic XYZ |
47 | 34 | ,#+include: ../../docs/include-topic.org |
48 | 35 | #+end_example |
49 | 36 |
|
| 37 | +* Building |
| 38 | + |
| 39 | +Each doc source file may be /exported/ to HTML or PDF manually (eg by ~emacs~ or less nicely by ~pandoc~). The build system performs this export automatically if Emacs is available. See also [[Publishing][Publishing]] below. |
| 40 | + |
| 41 | +** Automatic |
| 42 | + |
| 43 | +By default, the docs are not built. Their build is initiated with the command line option ~--docs=<...>~. It takes a list of transformations. Currently all transformations can be exercised with: |
| 44 | + |
| 45 | +#+begin_example |
| 46 | + waf --docs=org2html,org-pdf |
| 47 | +#+end_example |
| 48 | + |
| 49 | +This will build all documents. |
| 50 | + |
| 51 | +** Individual |
| 52 | + |
| 53 | +Individual documents can be built via the usual Waf target mechanism: |
| 54 | + |
| 55 | +#+begin_example |
| 56 | + waf --docs=org2html list |
| 57 | + waf --docs=org2html --target=docs-README-html |
| 58 | + waf --docs=org2pdf --target=docs-README-pdf |
| 59 | + evince build/docs/README.pdf |
| 60 | +#+end_example |
| 61 | + |
| 62 | +** Manual |
| 63 | + |
| 64 | +Of course it is possible to manually transform the org documents to HTML or PDF. Care must be taken to not leave the exported products in the source tree. Do not ever commit generated documentation to the repo. |
| 65 | + |
| 66 | +*** Using Emacs |
| 67 | + |
| 68 | +Visit the org file and type ~C-c C-e h h~ to export it to HTML. Alternatively, ~C-c C-e l p~ will export to PDF. |
| 69 | + |
| 70 | +#+begin_note |
| 71 | +Results may differ from officially published version. In particular, code syntax highlighting is sensitive Emacs customization. |
| 72 | +#+end_note |
| 73 | + |
| 74 | +*** Using pandoc |
| 75 | + |
| 76 | +If you are afraid of Emacs you can use ~pandoc~ to generate previews. For example: |
| 77 | + |
| 78 | +#+begin_example |
| 79 | + cd docs |
| 80 | + pandoc -o README.html README.org |
| 81 | + pandoc -o README.pdf README.org |
| 82 | +#+end_example |
| 83 | + |
| 84 | +#+begin_note |
| 85 | +The results with pandoc will be rather plain and ugly compared to what is produced by Emacs. |
| 86 | +#+end_note |
| 87 | + |
| 88 | + |
| 89 | +* Authoring |
| 90 | + |
| 91 | +There is a huge body of guidance on authoring documents in org markup. Here, only a few special things relevant to WCT documentation are given. To get started: |
| 92 | + |
| 93 | +#+begin_example |
| 94 | + git clone [email protected]:wirecell/wire-cell-toolkit.git /path/to/wct |
| 95 | + cd /path/to/wct |
| 96 | + $EDITOR <pkg>/docs/somefile.org |
| 97 | +#+end_example |
| 98 | + |
| 99 | +Any text editor is fine to use though of course Emacs provides the most support. |
| 100 | + |
| 101 | +** File links |
| 102 | + |
| 103 | +In addition to linking to web URLs, relative links to other files are allowed. The form that should be used is: |
| 104 | + |
| 105 | +#+begin_example |
| 106 | + See [[file:other.org][this other file]] for more info. |
| 107 | +#+end_example |
| 108 | + |
| 109 | +Publishing will include the targets of these links. |
| 110 | + |
| 111 | +** Images |
| 112 | + |
| 113 | +Documents may include images. They are typically placed in the ~docs/~ directory alongside the org source. |
| 114 | + |
| 115 | +#+begin_example |
| 116 | + Enjoy this figure: |
| 117 | + |
| 118 | + [[file:/wire-cell-bee-logo.png]] |
| 119 | +#+end_example |
| 120 | + |
| 121 | +[[file:wire-cell-bee-logo.png]] |
| 122 | + |
| 123 | +Graphics files can pose a problem for allowing the org source to export to both HTML and PDF (by way of LaTeX). Use of PNG and JPEG is compatible with both but for some content leads to poor resolution or large files. Use of PDF images is best for PDF export and for line-art but PDF will not be inlined in HTML export and will instead be presented as a link. In principle, SVG can be used for both and has good resolution/size features but use in PDF/LaTeX export requires some special attention. |
| 124 | + |
| 125 | +** File inclusion |
| 126 | + |
| 127 | +Avoid including other org files as this causes ambiguity in relative links and goes against the "one org file per document" pattern that the build assumes. |
| 128 | + |
| 129 | +* Previewing |
| 130 | + |
| 131 | +While editing it can be useful to see a rendered version. One may simply build a document as described in [[Building][Building]]. This can be coupled with a "live view" previewing. |
| 132 | + |
| 133 | +** PDF |
| 134 | + |
| 135 | +The ~evince~ or ~atril~ PDF viewers provide "live view", reloading when the PDF updates. |
| 136 | + |
| 137 | +** HTML |
| 138 | + |
| 139 | +A "live view" of the HTML file can be useful as one edits. This can approximate "instant" publishing. It may be used like: |
| 140 | + |
| 141 | +#+begin_example |
| 142 | + cd /path/to/wct |
| 143 | + ln -s docs/styles . |
| 144 | + livereload -d -p 5959 -t . |
| 145 | +#+end_example |
| 146 | +The reason for the symlink is to make the source area look like the published web area. |
| 147 | + |
| 148 | +#+begin_tip |
| 149 | +The command may be installed with ~pip install livereload~. It may be convenient to install this in the same Python environment as ~wire-cell-python~. |
| 150 | +#+end_tip |
| 151 | + |
| 152 | +#+begin_note |
| 153 | +File tree indices (~index.html~) are not automatically generated by ~livereload~ so you will must type in the full path to an HTML file in the URL. For example, the top level README would be at the URL http://127.0.0.1:5959/README.html. |
| 154 | +#+end_note |
50 | 155 |
|
51 | | -* HTML |
| 156 | +* Publishing |
52 | 157 |
|
53 | | -Each WCT documentation file may be exported in-place to an HTML file. |
54 | | -Links should be relative. However, CSS and javascript files are found |
55 | | -using an absolute URL rooted at ~/~. When the exported HTML is |
56 | | -installed to the ~wirecell.github.io~ package and served from that |
57 | | -domain or https://wirecell.bnl.gov/ this path will be assured. When |
58 | | -developing the documentation it is useful to run a local server such |
59 | | -as with: |
| 158 | +We publish the WCT source docs by "installing" the exported HTML files into the ~git~ repo that holds the WCT web site. |
60 | 159 |
|
61 | 160 | #+begin_example |
62 | | -$ pip install livereload |
63 | | -$ livereload -p 5959 -t /path/to/wire-cell-toolkit |
| 161 | + git clone [email protected]:WireCell/wirecell.github.io /path/to/web |
| 162 | + git clone [email protected]:wirecell/wire-cell-toolkit.git /path/to/wct |
| 163 | + |
| 164 | + cd /path/to/wct |
| 165 | + waf configure [...] |
| 166 | + waf install --docs=org2html --docs-prefix=/path/to/web |
| 167 | + |
| 168 | + cd /path/to/web |
| 169 | + git commit |
| 170 | + git push |
64 | 171 | #+end_example |
65 | 172 |
|
| 173 | +#+begin_tip |
| 174 | +By default, the ~waf install --docs=org2html~ command will launch a new instance of Emacs for each org file. This can be slow. An optional optimization is supported that will speed up the build by about 4x. To use it, first start ~emacs~ and there issue ~M-x (server-start)~. Then build with: ~waf install --docs=org2html --emacs-daemon="server"~. |
| 175 | +#+end_tip |
| 176 | + |
| 177 | +* Other markup |
| 178 | + |
| 179 | +Org markup syntax is very simple and plain text. You may use any editor to author it. Above gives various ways to convert to HTML or PDF without using or knowing Emacs. |
| 180 | + |
| 181 | +In principle, other markup formats could be supported, but this is discouraged. Supporting a new markup format requires a developer to "champion" the formation. Requirement on the developer include: |
| 182 | + |
| 183 | +- Demonstrate that they will actually provide and maintain documentation. |
| 184 | + |
| 185 | +- Explain why they are incapable of using org. |
| 186 | + |
| 187 | +- Develop a waf tool to integrate the formst that operates symmetric with the [[file:../waft/org.py][org waf tool]]. |
| 188 | + |
| 189 | +- Provide HTML CSS/JS styling. |
| 190 | + |
| 191 | +* Other documentation |
| 192 | + |
| 193 | +WCT has additional documentation beyond what is housed in the source repo. See entry point at: |
| 194 | + |
| 195 | +- https://wirecell.bnl.gov/ |
| 196 | + |
| 197 | +- https://wirecell.github.io/ (mirror) |
0 commit comments