Remaining work

Those are the known issues and limitations of the debmans software, serving as an internal, ad-hoc issue tracker.

Blocking

Those are the things that need to be done to complete the restoration of the manpages service.

  • 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
  • setup virtual host configuration, include:
    • redirections for previous links (see man-cgi/INSTALL and maybe more)
    • 404 handler to point to 404.html
    • edit cii badge when done, future section
    • CSP and various other SSL flags?
  • 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.org DNS to point to the static.d.o DNS. at this point, the MVP is in place

Important

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
    1. whatis(1): find manpages by name (done with custom Javascript)
    2. apropos(1): find manpages by description
    3. full text search

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)
  • move apt_cache optimizations upstream
  • rotated –logfile
  • 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)
  • 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...
  • embed test suite in main program
  • consider a plugin system for extending to more than manpages, would provide the default for --plugin

Possible optimizations

Optimization ideas:

  • 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

Those are todo items extracted from the code. Priority of those is indeterminate unless otherwise noted.

Todo

the click module decorators make all the click.command() functions hidden from Sphinx. This is presumably because the signature changes from a func to a cls, but remains to be confirmed.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/debmans/checkouts/1.0.0/doc/api.rst, line 8.)