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

KDE's Doxygen guidelines are available online.