Commit e5c2bd8b14341d82b0d07da560298b85db110ef1
1 parent
29384eca
TODO: doc conversion notes
Make a list of things that need to be done while converting docbook to sphinx/rst.
Showing
1 changed file
with
62 additions
and
0 deletions
TODO
| ... | ... | @@ -17,6 +17,68 @@ Next |
| 17 | 17 | thrown when an uninitialized trailer is accessed provides useful |
| 18 | 18 | information. Test from the C API as well as the C++ API. |
| 19 | 19 | |
| 20 | +Doc conversion Notes | |
| 21 | +==================== | |
| 22 | + | |
| 23 | +Things to fix: | |
| 24 | + | |
| 25 | +Entities/Unicode | |
| 26 | + | |
| 27 | +Gajic -> Gajić | |
| 28 | + | |
| 29 | +<!ENTITY lastreleased "November 16, 2021"> (not needed) | |
| 30 | +<!ENTITY ldquo "“"> | |
| 31 | +<!ENTITY mdash "—"> | |
| 32 | +<!ENTITY nbsp " "> | |
| 33 | +<!ENTITY ndash "–"> | |
| 34 | +<!ENTITY rdquo "”"> | |
| 35 | +<!ENTITY swversion "10.4.0"> -> |release| | |
| 36 | + | |
| 37 | +Elements: | |
| 38 | + | |
| 39 | +See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html | |
| 40 | + | |
| 41 | +<appendix>/<chapter>/<preface> -- no distinction | |
| 42 | +<programlisting> went to :: -- check them each | |
| 43 | +Make sure the information from <book> is in there | |
| 44 | +<xref> -- find #ref. in converted rst | |
| 45 | +Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh --> | |
| 46 | + | |
| 47 | +<application>, <command> -> :command: | |
| 48 | +<filename> -> :file: (allows {x}) | |
| 49 | +<option> -> :samp: (allows {x}) | |
| 50 | +<firstterm> -> just use literal | |
| 51 | +<replaceable> -> Make sure in :file: or :samp:, then use {} | |
| 52 | + | |
| 53 | +Build: | |
| 54 | + | |
| 55 | +apt install python3-pip texlive-latex-extra latexmk | |
| 56 | +pip install sphinx | |
| 57 | + | |
| 58 | +sphinx-build -M help . . | |
| 59 | +sphinx-build -M latexpdf source build | |
| 60 | +sphinx-build -M html source build | |
| 61 | +sphinx-build -M singlehtml source build | |
| 62 | + | |
| 63 | +autoconf should detect sphinx and its dependencies, not fop, etc. | |
| 64 | +Remove VALIDATE_DOC | |
| 65 | +Fix installation of documentation in doc | |
| 66 | + | |
| 67 | +Additional cleanup: | |
| 68 | + | |
| 69 | +* Indices and tables section | |
| 70 | + | |
| 71 | +Future work: | |
| 72 | + | |
| 73 | +* :ref: -- would be nice if it were suitable for printed documentation | |
| 74 | +* README-maintainer: Fix installation of documentation to website | |
| 75 | +* Release notes link changed (need #ref.release-notes as well as #release-note) | |
| 76 | +* Decide about readthedocs; if using, with multiple versions/latest | |
| 77 | +* Change order of sections | |
| 78 | +* Get navigation working properly | |
| 79 | +* Generate stuff (options, code samples, etc.) as needed | |
| 80 | +* Figure out where to put :ref:`search` so we get doc search | |
| 81 | + | |
| 20 | 82 | Documentation |
| 21 | 83 | ============= |
| 22 | 84 | ... | ... |