Package: doxytag2zealdb
doxytag2zealdbdoxytag2zealdb creates a SQLite3 database from a Doxygen tag file to enable
searchable Doxygen docsets with categorized entries in tools likehelm-dash,Zeal, andDash.IntroductionDoxygen'sGENERATE_DOCSETconfiguration option does most of the work to
get a usable docset for use with helm-dash and friends. However, one still has
to write a SQLite3 database to facilitate searching and browsing by entry type.doxytag2zealdb usesBeautiful Soupto traverse Doxygen tag files, then
extracts and prepares entries to write to the DB as suggested in theDash guide on generating docsets. By default, it also updatesInfo.plist, which is expected to be one directory-level up from the output
DB, to indicate that a Dash-style docset index is used (for Dash users). This
can be disabled by specifying--dont-update-info-plist.doxytag2zealdb has been developed against the Doxygen tag file output for a few
C++ codebases. At present:Several Doxygen tag file entry types are mapped to their corresponding docset
entry types. There may be more mapping opportunities to theentry typesin the docset generation guide.There are command-line options to include function arguments and return types
in entry names (e.g.,some_func(int &output, const double input) -> boolby
specifying--include-function-signatures) and include the parent scope in
entry names for class/struct/namespace members (e.g.,SomeClass::Methodby
specifying--include-parent-scopes). These options can be combined.RequirementsPython 2.7 or Python 3 withbeautifulsoup4(4.4.1),lxml(3.6.0), anddocopt(0.6.2)InstallationThedoxytag2zealdbmodule can be executed directly from a repository
clone or extracted source tarball, provided that the requirements are
installed, usingpython -m doxytag2zealdb.Alternatively, one may may runsetup.py(python setup.py install) or
install from PyPI (pip install [--user] [--upgrade] doxytag2zealdb). Note
that the entrypoint is simplydoxytag2zealdbwhen installing via these
methods.Typical UsageSuppose you have a project namedfoowith Doxygen configuration infoo.dox. As suggested in theDoxygen section of the Dash docset guide, at least make sureGENERATE_DOCSET = yesinfoo.dox. Ensure HTML output is enabled and
also specify tag file generation withGENERATE_TAGFILE = /path/to/desired/foo.tag. You may wish to further
customizeDOCSET_BUNDLE_ID(which controls the name of the docset
subdirectory), otherDOCSET_*options, and the other options mentioned in
the guide.If the top-level Doxygen output directory isoutput, go tooutput/html/and runmake. An error about missingdocsetutilis fine (and expected
when not using macOS and an old-enough Xcode install). Also,output/html/$(DOCSET_BUNDLE_ID).docset/Contents/Info.plistshould have
theisDashDocsetkey set totrue. doxytag2zealdb will do this
automatically; additionally pass--dont-update-info-plistin the next step
if this is not desired.The SQLite DB is expected to be nameddocSet.dsidxand placed in the
directoryoutput/html/$(DOCSET_BUNDLE_ID).docset/Contents/Resources/,
where$(DOCSET_BUNDLE_ID)may be something likeorg.doxygen.Projectif
left uncustomized infoo.dox. This is where doxytag2zealdb comes in:[python -m] doxytag2zealdb --tag /path/to/desired/foo.tag \
   --db /path/to/output/html/$(DOCSET_BUNDLE_ID).docset/Contents/Resources/docSet.dsidx \
   --include-parent-scopes --include-function-signaturesAfter adding an icon and whatever else,output/html/$(DOCSET_BUNDLE_ID).docsetshould be ready to use with the
tool of your choice.Extending ItThere are multiple ways to extend doxytag2zealdb's behavior:Options can be added to existingTagProcessors. SeeTagProcessorandfunctionTagProcessorfor examples of this. Also see how keyword arguments
get passed around fromdoxytag2zealdb.pytoTagfileProcessortoTagProcessors and their superclasses.One can subclassTagProcessor(or one of its existing child classes) to
handle a new tag case. Then add it to the registrations inTagfileProcessor.init_tag_processors()or separately register it at
runtime, if you like.Command-line options are easily added usingdocopt. See the module
docstring and code indoxytag2zealdb.py....ContributingPlease file issues and submit pull (merge) requests upstream athttps://gitlab.com/vedvyas/doxytag2zealdb.Licensedoxytag2zealdb is distributed under the terms of the GNU General Public License
version 3 or (at your option) any later version. Please see COPYING.