Package: debmans
debmansis a tool to extract documentation (currently manpages) from
Debian packages and transform them into HTML for viewing with a normal
web browser.This suite of tools is designed to run onmanpages.debian.org,manpages.ubuntu.com,linux.die.netor similar services.ExampleYou can do a test run of this software against your local APT cache,
like this:$ ( cd /var/cache/apt/archives/ && dpkg-scanpackages . | sudo tee Packages > /dev/null )
dpkg-scanpackages: warning: package tar (filename ./tar_1.27.1-2+b1_amd64.deb) is repeat;
dpkg-scanpackages: warning: ignored that one and using data from ./tar_1.27.1-2+deb8u1_amd64.deb!
$ debmans -m /var/cache/apt/archives -o html -v --progress extract render site serve
extracting files matching patterns: (u'man/(?:\\w+/)?man[1-9]/.+\\.[1-9]\\w*(?:\\.gz)?$',) in mirror /var/cache/apt/archives
extracting packages  [####################################]  100%
completed inspection of 564 packages, extracted 559 files
received 559 paths from extractor
rendering manpages  [#################################---]   92%  0d 00:00:02man2html: unable to open or read file man1/dmenu.1
rendering manpages  [####################################]  100%
looking for static files to render in *.mdwn
Serving HTTP on 0.0.0.0 port 8000...Your rendered manpages will be available at <http://localhost:8000/>.Note that you will needdpkg-scanpackagesfrom thedpkg-devpackage to run the
above test. The warnings can be safely ignored.debmansdoesn’t
normally requiredpkg-devin operation if you use a properly
configured mirror.Common tasksA more normal run would be to run on a regular mirror. This will extract
all manpages from the given mirror and convert to HTML:debmans --mirror /srv/mirror --output static extract renderThis can be ran repeatedly and only extracted manpages will be rendered.Extraction onlyYou can also run the process step by step, for example, this will only
extract the manpages:debmans -m /srv/mirror -o html extractNote that extract creates a cache in the output directory to avoid
re-extracting already found archives. Render also uses a caching
mechanism by not converting to HTML if the HTML version is newer than
the manpage. Those mechanisms can be disabled with--no-cache.debmans -m /srv/mirror -o html --no-cache extractYou can make a trial run with the-nflag and enable more verbose
logging:debmans -v -n -m /srv/mirror -o manpages extractRendering onlyRendering the pages can be done separately with:debmans -o html render --srcdir manpagesThis is especially important if the extraction process was interrupted,
as only part of the manpages will be rendered on subsequent runs.Manpages are currently rendered withman2htmlbut
this can be changed with the-rflag, although no other renderer has
been tested and the output may not be compatible withman2html.Static pages renderingThe templating engine is fairly simple, based on Jinja2, which uses
standard{{foo}}placeholders. The template is instatic/template.htmland should be following debian.org’s graphic
design conventions.This should generate the markdown files:debmans -o html siteUse--prefixif the directory is not at the root of the host.Installationdebmanscan be installed through pip with:pip install debmansSource code can also be found onGitlabwith Git or as a tarball, or
on Debian’scollab-maint repository.The source code is should be installed with:./setup.py installIt can also be ran from the source tree directly with:python -m debmans renderThe dependencies are listed in thesetup.pyfile.Acknowledgementsdebmanswas written by Antoine Beaupré and is licensed under the
Affero GPLv3, seelicensefor the complete license.Parts of this software were inspired by a review of existing tools, most
notably theUbuntu manpages
converteranddgilman’s converter. Thesources.debian.netservice source code
and design was also directly used in some parts, which is partly whydebmansis licensed under the AGPL.Also thanks to Paul Wise for nudging me along and all the help
navigating the various tools and protocols to make all this work.This project mostly follows theCore
Infrastructurebest
practices, see thefull
reportfor details.