Those are the known issues and limitations of the
serving as an internal, ad-hoc issue tracker.
Those are the things that need to be done to complete the restoration of the manpages service.
- setup virtual host
- redirections for previous links:
- 404 handler to point to 404.html
- edit cii badge when done, future section
- CSP and various other SSL flags?
- CGI config: currently implemented with Flask, see the
for a list of deployment possibilities. simplest is probably to
provide WSGI and CGI shims. WSGI works well in apache (and also
works in Nginx) according digital ocean
CGI works everywhere. Also: need a way to pass configs
debmans.search.main()actually) between apache and CGI
- redirections for previous links:
- test run on manziarly
- requires access to manpages group? see RT#6485
- missing dependencies to run properly (even as plain user): setuptools, click, apt, debian, patch to mirror/debian.org.git
- provide DSA team with Puppet ruleset (see dsa-puppet manifests) or config documentation
- ask DSA to deploy the new code, test
- if it works, fix the
manpages.debian.orgDNS to point to the static.d.o DNS. at this point, the MVP is in place
Those are not part of the Minimum Viable Product, but would be important to implement to make this software complete.
- search functionality, in that order
- whatis(1): find manpages by name (done by Flask app)
- apropos(1): find manpages by description
- full text search
- i18n: we parse all languages, but should auto-detect the web browser’s language with fallbacks and everything. Apache auto-negociation? Could be like debian.org language menus... The trick is to guess the language list again, similar to the suites issue. The new search box can lookup different locales in the backend, but doesn’t have the list of locales in the frontend.
Nice to have¶
Those are not really necessary but could improve the service.
unify site and render? a .mdwn file is like a .1.gz file, basically, except it’s not extracted from a .deb
100% test coverage (about 80% now), edit cii badge when done (quality section)
add sections browser to the index page?
debian packaging, edit cii badge when done (future and other sections)
use tox to test against different py envs
CII suggestions, edit cii badge when done:
- continuous integration through Gitlab CI? (quality section)
- hook pyflakes in test suite (quality section)
- static code analysis with pylint (analysis section)
embed test suite in main program
consider a plugin system for extending to more than manpages, would provide the default for
- look at the archive’s
Contents-*files to choose which packages to extract
- extract only targeted files from the archive instead of iterating over it? not sure it’s an improvement...
- use os.scandir() where relevant, instead of os.walk() and stat
- use multiprocessor.Pool for background job rendering? maybe by firing up rendering as soon as pages are created
- use md5sums to check if files were modified, edit cii badge when implemented (security section)
- pre-compile all regexes
Those will be implemented as needed, remember:
Premature optimization is the root of all evil. – Donald Knuth
Internal code tasks¶
todo items extracted from the code. Priority of those is
indeterminate unless otherwise noted.
we should probably have derived Template directly here.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/latest/debmans/renderer.py:docstring of debmans.renderer.JinjaRenderer, line 7.)
support %(target)s instead of standard output, if necessary?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/latest/debmans/renderer.py:docstring of debmans.renderer.CommandRenderer.render, line 6.)
this assumes cross-references are done with the
macro, which is unfortunately not often the case in my
tests. so some manual cross-ref will be required here.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/latest/debmans/renderer.py:docstring of debmans.renderer.MandocRenderer, line 3.)
croaks on the
kodi(1) manpage, a weird redirect,
which we should handle manually here. the fix, according
mandoc(1) is to chdir to the correct relative
directory. looking at
.so looks like
an “include” directive.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/latest/debmans/renderer.py:docstring of debmans.renderer.MandocRenderer, line 7.)
this may be slow in large directories and may be
os.scandir() if we ever depend on
Python 3.5 or later.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/latest/debmans/renderer.py:docstring of debmans.renderer.find_files, line 4.)
document that compressed manpages are mandatory
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/envs/latest/local/lib/python2.7/site-packages/click-6.7-py2.7.egg/click/core.py:docstring of debmans.renderer.render, line 11.)