KApiDox

README.md
1 # KDE Doxygen Tools
2 
3 ## Introduction
4 
5 This framework contains scripts and data for building API documentation (dox) in
6 a standard format and style.
7 https://api.kde.org holds the result.
8 
9 The [Doxygen](https://www.doxygen.nl) tool performs the actual documentation extraction and
10 formatting. This framework provides a wrapper script to make generating the
11 documentation more convenient (including reading settings from the target
12 framework or other module) and a standard template for the generated
13 documentation.
14 
15 
16 ## Dependencies
17 
18 ### Required
19 You need Python 3 to run the scripts. Additionally you
20 need to have the jinja2 and yaml (or pyyaml) modules.
21 
22 The following command should install them for the current user:
23 
24  pip install --user PyYAML jinja2
25 
26 Of course, you need Doxygen!
27 
28 ### Optional
29 Doxyqml and doxypypy might be needed to let doxygen document qml
30 and python sources respectively.
31 
32 To generate the dependency diagrams, you need the Graphviz Python bindings.
33 They are currently not available from pip, but most distributions provide them.
34 You can get binaries and source archives from
35 <https://www.graphviz.org/download/>.
36 
37 ## Installation
38 
39 Unlike almost every other KDE module, kapidox does not use CMake. This is
40 because it is purely written in Python, and so uses distutils. While it does
41 not need to be installed to be used (see below), you can install kapidox with
42 
43  python setup.py install
44 
45 Note: For consistency, kapidox provides a CMakeLists.txt file, but this is just
46 a wrapper around the setup.py script.
47 
48 
49 ## Writing documentation
50 
51 Writing dox is beyond the scope of this documentation -- see the notes at
52 <https://community.kde.org/Frameworks/Frameworks_Documentation_Policy> and the [doxygen
53 manual](https://doxygen.nl/manual/docblocks.html).
54 
55 To allow code to handle the case of being processed by kapidox a C/C++ preprocessor macro
56 is set as defined when run: `K_DOXYGEN` (since v5.67.0).
57 For backward-compatibility the definition `DOXYGEN_SHOULD_SKIP_THIS` is also set, but
58 its usage is deprecated.
59 
60 The kapidox scripts expects certain things to be present in the directory it is
61 run on:
62 
63 ### README.md
64 Most importantly, there should be a `README.md` file, like this page (backward
65 compatibility also authorize `Mainpage.dox` files). The first line of this file
66 is particularly important, as it will be used as the title of the documentation.
67 
68 ### metainfo.yaml
69 A `metainfo.yaml` file is needed for the library to be generated. It should
70 contain some meta information about the library itself, its maintainers, where
71 the sources are, etc.
72 
73 A very simple example can be:
74 
75 ```yaml
76 # metainfo.yaml
77 description: Library doing X
78 maintainer: gwashington
79 public_lib: true
80 logo: libX.png
81 ```
82 
83 A comprehensive list of the available keys can be found on
84 [this page](@ref metainfo_syntax).
85 
86 By default, the source of the public library must be in `src`, if the
87 documentation refers to any dot files, these should be in `docs/dot`.
88 Images should be in `docs/pics`, and snippets of example code should be in
89 `examples`. See the doxygen documentation for help on how to refer to these
90 files from the dox comments in the source files.
91 
92 If you need to override any doxygen settings, put them in a `docs/Doxyfile.local` in your project.
93 Global settings are defined in `src/kapidox/data/Doxyfile.global`.
94 
95 ## Generating the documentation
96 
97 The tool for generating dox is `src/kapidox_generate`.
98 Change to an empty directory, then simply point it at the
99 folder you want to generate dox for (such as a frameworks checkout).
100 
101 For example, if you have a checkout of KCoreAddons at
102 ~/kde/src/frameworks/kcoreaddons, you could run
103 
104  ~/kde/src/frameworks/kapidox/src/kapidox_generate ~/kde/src/frameworks/kcoreaddons
105 
106 and it would create a documentation in the current directory, which needs to be empty before executing the command.
107 
108 kapidox recursively walks through folders, so you can also run it on
109 `~/kde/src/frameworks` or `~/src`. For a lot of libraries, the generation can last
110 15-30 minutes and use several hundreds of MB, so be prepared!
111 
112 Pass the --help argument to see options that control the behaviour of the
113 script.
114 
115 Note that on Windows, you will need to run something like
116 
117  c:\python\python.exe c:\frameworks\kapidox\src\kapidox_generate c:\frameworks\kcoreaddons
118 
119 ## Specific to frameworks (for now)
120 
121 You can ask `kgenframeworksapidox` to generate dependency diagrams for all the
122 frameworks. To do so, you must first generate Graphviz .dot files for all
123 frameworks with the `depdiagram-prepare` tool, like this:
124 
125  mkdir dot
126  ~/kde/src/frameworks/kapidox/src/depdiagram-prepare --all ~/kde/src/frameworks dot
127 
128 Then call `kgenframeworksapidox` with the `--depdiagram-dot-dir` option, like
129 this:
130 
131  mkdir frameworks-apidocs
132  cd frameworks-apidocs
133  ~/kde/src/frameworks/kapidox/src/kapidox_generate --depdiagram-dot-dir ../dot ~/kde/src/frameworks
134 
135 More fine-grained tools are available for dependency diagrams. You can learn
136 about them in [depdiagrams](@ref depdiagrams).
137 
138 
139 ## Examples of generated pages:
140 
141 - KDE API documentation: <https://api.kde.org/>
142 
143 ## Licensing
144 
145 This project is licensed under BSD-2-Clause. But the specific theme used inside KDE
146 is licensed under AGPL-3.0-or-later. If you find the AGPL to restrictive you can
147 alternatively use the theme from [Docsy](https://github.com/google/docsy) (APACHE-2.0).
148 For that you need to replace the style and js script present in `src/kapidox/data/templates/base.html`.
149 
150 If you need support or licensing clarification, feel free to contact the maintainers.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Oct 15 2021 22:55:57 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.