Warning, /frameworks/kapidox/README.md is written in an unsupported language. File is not indexed.
0001 # KDE Doxygen Tools 0002 0003 ## Introduction 0004 0005 This framework contains scripts and data for building API documentation (dox) in 0006 a standard format and style. 0007 0008 https://api.kde.org holds the result, and this very page is handled by KApiDox too: https://api.kde.org/frameworks/kapidox/html/index.html. 0009 0010 The [Doxygen](https://www.doxygen.nl) tool performs the actual documentation extraction and 0011 formatting. This framework provides a wrapper script to make generating the 0012 documentation more convenient (including reading settings from the target 0013 framework or other module) and a standard template for the generated 0014 documentation. 0015 0016 ## Installation 0017 Python 3 is required to run the scripts, as well as the `jinja`, `pyyaml`, `requests`, `doxypypy` and `doxyqml` python modules. 0018 0019 The following command creates a venv and installs the tool alongside all its modules: 0020 0021 ``` 0022 bash ./bootstrap-devenv.sh 0023 ``` 0024 0025 To generate the dependency diagrams, you need the Graphviz Python bindings. 0026 They are currently not available from pip, but most distributions provide them. 0027 You can get binaries and source archives from 0028 <https://www.graphviz.org/download/>. 0029 0030 ## (For maintainers) updating the package dependencies 0031 0032 Run ./requirements-update.sh in this folder, review and test the updated requirements file and commit the changed file. 0033 0034 ## Workflow 0035 0036 This document describes two ways to use KApiDox to generate documentation for KDE software: the manual way, and the container way. Both can apply to standalone repositories or to projects built using [kdesrc-build](https://community.kde.org/Get_Involved/development#Set_up_kdesrc-build), but the main role of the manual method is mostly to learn how the tool works, whereas the container method should be the cleaner, more convenient way. 0037 0038 ### The manual way 0039 0040 With this method, we will be using three directories (kirigami, kapidox and kirigamidocs). 0041 0042 First, clone the desired repository as well as the KApiDox repository. In this example we will use Kirigami: 0043 0044 ```bash 0045 git clone https://invent.kde.org/frameworks/kirigami.git 0046 git clone https://invent.kde.org/frameworks/kapidox.git 0047 ``` 0048 0049 You may use the ssh:// version instead if you have a developer account. 0050 0051 You should now have a `kirigami` and a `kapidox` folder. Make a new folder to store the local test HTML documentation, then switch to the kapidox directory: 0052 0053 ```bash 0054 mkdir kirigamidocs 0055 cd kapidox 0056 ``` 0057 0058 Run the script provided by the KApiDox repository. This only needs to be done once, and it will download and install the needed Python3 modules and generate a proper Python virtual environment: 0059 0060 ```bash 0061 bash bootstrap-devenv.sh 0062 ``` 0063 0064 After the script is done, you should have a hidden folder called `.kapidox_venv/`, inside of which is a `bin/` folder containing the files we will be using. If the shell you are using is bash or zsh, you can run `./activate` to activate the Python virtual venv. If you are using csh or fish, you may use `./activate.csh` or `./activate.fish`, respectively. 0065 0066 After activating the Python venv, your terminal prompt should change to that of a venv. Switch to the folder we created earlier and run kapidox-generate by pointing to the folder containing the target project repository (in this case, Kirigami): 0067 0068 ```bash 0069 cd ../kirigamidocs 0070 kapidox-generate ../kirigami 0071 ``` 0072 0073 It can take a while. After it is done, for convenience, do not close this venv shell yet. 0074 0075 You should have an `index.html` file which should be the entrypoint of the new documentation. You can open a new instance of your terminal or another tab, then open it directly from your terminal by using `xdg-open index.html` or `kioclient exec index.html`, or whichever other method you'd like. 0076 0077 After that, you may edit the Doxygen-formatted documentation in *.qml or *.h files using Kate or your favorite editor. 0078 0079 After you're finished editing, you can switch back to the venv in the `kirigamidocs/` folder, check that you are in the correct folder with `pwd`, and run the following to regenerate the locally edited documentation: 0080 0081 ```bash 0082 pwd // outputs ~/kirigamidocs 0083 rm -rf * && kapidox-generate ../kirigami 0084 ``` 0085 0086 Now that you understand how to generate the venv and how to use `kapidox-generate`, you can easily apply this knowledge to projects built using kdesrc-build. Assuming you're using bash: 0087 0088 ```bash 0089 kdesrc-build kapidox 0090 // ...building... 0091 kdesrc-build kirigami 0092 // ...building... 0093 mkdir ~/kirigamidocs 0094 cd ~/kde/src/kapidox 0095 bash bootstrap-devenv.sh 0096 source .kapidox_venv/bin/activate 0097 cd ~/kirigamidocs 0098 kapidox-generate ~/kde/src/kirigami 0099 // ...edit files... 0100 rm -rf * && kapidox-generate ~/kde/src/kirigami 0101 ``` 0102 0103 ### The container way 0104 0105 Although it is possible to use KApiDox directly, using it in a container can be much more convenient once it is set up. 0106 0107 You can build a new image with docker or podman: 0108 0109 ```bash 0110 docker build . -t kapidox_generate:latest 0111 // OR 0112 podman build . -t kapidox_generate:latest 0113 ``` 0114 0115 By running `docker images` or `podman images` you should now see an image called `localhost/kapidox_generate`. 0116 0117 To run `kapidox-generate` with a project that you want to generate the docs from you need an empty folder for the results (`/path/to/build/folder`). The build directory inside the container is set as `BUILD_DIR` in `Dockerfile`, and must stay in sync with what is used as `CONTAINER_BUILD_DIR` in the volume mapping. 0118 0119 For this example we use `libksane` checked out to `/path/to/libksane`: 0120 0121 ```bash 0122 export HOST_PROJECT_SRC=/path/to/libksane/folder 0123 export HOST_BUILD_DIR=/path/to/libksane/build/folder 0124 export CONTAINER_PROJECT_SRC=/home/kapidox/libksane 0125 export CONTAINER_BUILD_DIR=/home/kapidox/apidox-build 0126 mkdir $HOST_BUILD_DIR 0127 docker run \ 0128 --volume $HOST_PROJECT_SRC:$CONTAINER_PROJECT_SRC \ 0129 --volume $HOST_BUILD_DIR:$CONTAINER_BUILD_DIR \ 0130 kapidox_generate:latest \ 0131 kapidox-generate $CONTAINER_PROJECT_SRC 0132 ``` 0133 0134 ## Writing documentation 0135 0136 Writing dox is beyond the scope of this documentation -- see the notes at 0137 <https://community.kde.org/Frameworks/Frameworks_Documentation_Policy> and the [doxygen 0138 manual](https://doxygen.nl/manual/docblocks.html). 0139 0140 To allow code to handle the case of being processed by kapidox a C/C++ preprocessor macro 0141 is set as defined when run: `K_DOXYGEN` (since v5.67.0). 0142 For backward-compatibility the definition `DOXYGEN_SHOULD_SKIP_THIS` is also set, but 0143 its usage is deprecated. 0144 0145 The kapidox scripts expects certain things to be present in the directory it is 0146 run on: 0147 0148 ### README.md 0149 Most importantly, there should be a `README.md` file that works as the main page, like one where this documentation is written in (backward compatibility also authorize `Mainpage.dox` files). The first line of this file 0150 is particularly important, as it will be used as the title of the documentation. 0151 0152 ### metainfo.yaml 0153 A `metainfo.yaml` file is needed for the library to be generated. It should 0154 contain some meta information about the library itself, its maintainers, where 0155 the sources are, etc. 0156 0157 A very simple example can be: 0158 0159 ```yaml 0160 # metainfo.yaml 0161 description: Library doing X 0162 maintainer: gwashington 0163 public_lib: true 0164 logo: libX.png 0165 ``` 0166 0167 A comprehensive list of the available keys can be found on 0168 [this page](@ref metainfo_syntax). 0169 0170 By default, the source of the public library must be in `src`, if the 0171 documentation refers to any dot files, these should be in `docs/dot`. 0172 Images should be in `docs/pics`, and snippets of example code should be in 0173 `examples`. See the [Doxygen documentation](https://doxygen.nl/manual/index.html) for help on how to refer to these 0174 files from the dox comments in the source files. 0175 0176 If you need to override any Doxygen settings, put them in a `docs/Doxyfile.local` in your project. 0177 Global settings are defined in `src/kapidox/data/Doxyfile.global`. 0178 0179 ## Generating the documentation 0180 0181 The tool for generating dox is `src/kapidox_generate`. 0182 Change to an empty directory, then simply point it at the 0183 folder you want to generate dox for (such as a frameworks checkout). 0184 0185 For example, if you have a checkout of KCoreAddons at 0186 ~/kde/src/frameworks/kcoreaddons, you could run 0187 0188 ~/kde/src/frameworks/kapidox/src/kapidox_generate ~/kde/src/frameworks/kcoreaddons 0189 0190 and it would create a documentation in the current directory, which needs to be empty before executing the command. 0191 0192 kapidox recursively walks through folders, so you can also run it on 0193 `~/kde/src/frameworks` or `~/src`. For a lot of libraries, the generation can last 0194 15-30 minutes and use several hundreds of MB, so be prepared! 0195 0196 Pass the --help argument to see options that control the behaviour of the 0197 script. 0198 0199 Note that on Windows, you will need to run something like 0200 0201 c:\python\python.exe c:\frameworks\kapidox\src\kapidox_generate c:\frameworks\kcoreaddons 0202 0203 ## Specific to frameworks (for now) 0204 0205 You can ask `kgenframeworksapidox` to generate dependency diagrams for all the 0206 frameworks. To do so, you must first generate Graphviz .dot files for all 0207 frameworks with the `depdiagram-prepare` tool, like this: 0208 0209 mkdir dot 0210 ~/kde/src/frameworks/kapidox/src/depdiagram-prepare --all ~/kde/src/frameworks dot 0211 0212 Then call `kgenframeworksapidox` with the `--depdiagram-dot-dir` option, like 0213 this: 0214 0215 mkdir frameworks-apidocs 0216 cd frameworks-apidocs 0217 ~/kde/src/frameworks/kapidox/src/kapidox_generate --depdiagram-dot-dir ../dot ~/kde/src/frameworks 0218 0219 More fine-grained tools are available for dependency diagrams. You can learn 0220 about them in [depdiagrams](@ref depdiagrams). 0221 0222 0223 ## Examples of generated pages: 0224 0225 - KDE API documentation: <https://api.kde.org/> 0226 0227 ## Licensing 0228 0229 This project is licensed under BSD-2-Clause. But the specific theme used inside KDE 0230 is licensed under AGPL-3.0-or-later. If you find the AGPL to restrictive you can 0231 alternatively use the theme from [Docsy](https://github.com/google/docsy) (APACHE-2.0). 0232 For that you need to replace the style and js script present in `src/kapidox/data/templates/base.html`. 0233 0234 If you need support or licensing clarification, feel free to contact the maintainers.