diff --git a/README.md b/README.md index f96f6cc..7a138c2 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,133 @@ # KDE Doxygen Tools ## Introduction This framework contains scripts and data for building API documentation (dox) in a standard format and style. The Doxygen tool is used to do the actual documentation extraction and formatting, but this framework provides a wrapper script to make generating the documentation more convenient (including reading settings from the target framework or other module) and a standard template for the generated documentation. ## Dependencies ### Required Python 2 or 3 is required to run the scripts. Whichever version of python you use needs to have the jinja2 and yaml (or pyyaml) modules. The following command should install them for the current user: pip install --user PyYAML jinja2 Of course, you need Doxygen! ### Optional Doxyqml and doxypypy might be needed to let doxygen document respectevely qml and python sources. To generate the dependency diagrams, you need the Graphviz Python bindings. They are currently not available from pip, but most distributions provide them. You can get binaries and source archives from -. +. ## Installation Unlike almost every other KDE module, kapidox does not use CMake. This is because it is purely written in Python, and so uses distutils. While it does not need to be installed to be used (see below), you can install kapidox with python setup.py install Note: For consistency, kapidox provides a CMakeLists.txt file, but this is just a wrapper around the setup.py script. ## Writing documentation Writing dox is beyond the scope of this documentation -- see the notes at - and the [doxygen -manual](http://www.stack.nl/~dimitri/doxygen/manual/). + and the [doxygen +manual](http://doxygen.nl/manual/docblocks.html). However, the script expects certain things to be present in the directory it is run on. ### README.md Most importantly, there should be a `README.md` file, like this page (backward compatibility also authorize `Mainpage.dox` files). The first line of this file is particularly important, as it will be used as the title of the documentation. ### metainfo.yaml A `metainfo.yaml` file is needed for the library to be generated. It should contain some metainformations about the library itself, its maintainers, where the sources are etc.. A very simple example can be: ```yaml # metainfo.yaml description: Library doing X maintainer: gwashington public_lib: true logo: libX.png ``` A comprehensive list of the available keys can be found on [this page](@ref metainfo_syntax). By default, the source of the public library must be in `src`, if the documentation refers to any dot files, these should be in `docs/dot`. Images should be in `docs/pics`, and snippets of example code should be in `examples`. See the doxygen documentation for help on how to refer to these files from the dox comments in the source files. If you need to override any doxygen settings, put them in `docs/Doxyfile.local`. A global settings file is defined in `src/kapidox/data/Doxyfile.global`. ## Generating the documentation The tool for generating dox is `src/kapidox_generate`. Simply point it at the folder you want to generate dox for (such as a framework checkout). For example, if you have a checkout of KCoreAddons at ~/src/frameworks/kcoreaddons, you could run ~/src/frameworks/kapidox/src/kapidox_generate ~/src/frameworks/kcoreaddons and it would create a documentation in the current directory. The folders are recursively walked through, so you can also run it on `~/src/frameworks` or `~/src`. For a lot of libraries, the generation can last 15-30 minutes and be several hundreds of Mb, so be prepared! Pass the --help argument to see options that control the behaviour of the script. Note that on Windows, you will need to run something like c:\python\python.exe c:\frameworks\kapidox\src\kapidox_generate c:\frameworks\kcoreaddons ## Specific to frameworks (for now) You can ask `kgenframeworksapidox` to generate dependency diagrams for all the frameworks. To do so, you must first generate Graphviz .dot files for all frameworks with the `depdiagram-prepare` tool, like this: mkdir dot ~/src/frameworks/kapidox/src/depdiagram-prepare --all ~/src/frameworks dot Then call `kgenframeworksapidox` with the `--depdiagram-dot-dir` option, like this: mkdir frameworks-apidocs cd frameworks-apidocs ~/src/frameworks/kapidox/src/kapidox_generate --depdiagram-dot-dir ../dot ~/src/frameworks More fine-grained tools are available for dependency diagrams. You can learn about them in [depdiagrams](@ref depdiagrams). ## Examples of generated pages: -- KDE API documentation: +- KDE API documentation: diff --git a/src/kapidox/data/templates/frontpage-sidebar.html b/src/kapidox/data/templates/frontpage-sidebar.html index 0ecea12..dfb5a42 100644 --- a/src/kapidox/data/templates/frontpage-sidebar.html +++ b/src/kapidox/data/templates/frontpage-sidebar.html @@ -1,32 +1,32 @@

KDE Products for developers

Description of what you can find here

If you are looking for documentation about KDE software or how to use Plasma, please refer to our userbase website.

Other KDE Products

Deprecated Products

diff --git a/src/kapidox_generate b/src/kapidox_generate index aabc2dd..4df9b28 100755 --- a/src/kapidox_generate +++ b/src/kapidox_generate @@ -1,110 +1,110 @@ #! /usr/bin/env python # -*- coding: utf-8 -*- # # Copyright 2014 Alex Merry # Copyright 2014 Aurélien Gâteau # Copyright 2014 Alex Turbov # Copyright 2016 Olivier Churlaud # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # Python 2/3 compatibility (NB: we require at least 2.7) from __future__ import division, absolute_import, print_function, unicode_literals import logging import codecs import os import sys import time import datetime if sys.version_info.major < 3: from urllib import urlretrieve else: from urllib.request import urlretrieve from kapidox import generator, utils, argparserutils, preprocessing, hlfunctions try: from kapidox import depdiagram DEPDIAGRAM_AVAILABLE = True except ImportError: DEPDIAGRAM_AVAILABLE = False def download_kde_identities(): """Download the "accounts" file on the KDE SVN repository in order to get the KDE identities with their name and e-mail address """ cache_file = os.path.join(utils.cache_dir(), 'kde-accounts') needs_download = True if os.path.exists(cache_file): logging.debug("Found cached identities file at %s", cache_file) # not quite a day, so that generation on api.kde.org gets a fresh # copy every time the daily cron job runs it yesterday = time.time() - (23.5 * 3600) if os.path.getmtime(cache_file) > yesterday: needs_download = False else: logging.debug("Cached file too old; updating") if needs_download: logging.info("Downloading KDE identities") try: if not utils.svn_export( 'svn://anonsvn.kde.org/home/kde/trunk/kde-common/accounts', cache_file, overwrite=True): logging.debug("Falling back to using websvn to fetch " "identities file") - urlretrieve('http://websvn.kde.org/*checkout*/trunk/kde-common/accounts', + urlretrieve('https://websvn.kde.org/*checkout*/trunk/kde-common/accounts', cache_file) except Exception as e: if os.path.exists(cache_file): logging.error('Failed to update KDE identities: %s', e) else: logging.error('Failed to fetch KDE identities: %s', e) return None maintainers = {} with codecs.open(cache_file, 'r', encoding='utf8') as f: for line in f: parts = line.strip().split() if len(parts) >= 3: maintainers[parts[0]] = { 'name': ' '.join(parts[1:-1]), 'email': parts[-1] } return maintainers def main(): kde_copyright = '1996-' + str(datetime.date.today().year) + ' The KDE developers' get_maintainers = download_kde_identities hlfunctions.do_it(maintainers_fct=get_maintainers, copyright=kde_copyright) if __name__ == "__main__": main()