robo9k / q3py Goto Github PK

Running make dist should;

• include all neccessary files

- [ ] be automated for GitHub releases

Add or at least mention the absence of or alternatives to:

• home page
  • downloads
  • manual (#4)
  • documentation
  • FAQ
  • blog / news
• forum
• mailing list
• IRC channel
• issue tracker
• wiki

and so on. Most of them are over the top for a project as small as q3py though 😉

The documentation is currently a mix of Doxygen and Sphinx with its breathe extension (since #14) on gh-pages.

It seems like Doxyen is mostly meant for inline code documentation. Other pages can be added as well, but they are just listed as "related pages" without any hierarchical structure.

Sphinx on the other hand allows for well structured prose, as well as plain code documentation. breathe can be used to import the existing Doxygen documentation, but it is not integrated that well (which might be the fault of Doxygen's XML output).

It seems like the best solution right now would be using readthedocs (instead of gh-pages) with plain Sphinx documents (without breathe and without Doxygen).

Sphinx is not integrated into the autotools via m4 macros right now, but then again q3py's portability is rather limited both by current implementation and (Quake 3 + Python 3) design.
Sphinx requires Python, but this is not a problem since q3py does so, too. If a recent enough Python 3 version is used, one gets pip and venv as well.

tl;dr: No decision on documentation right now, mostly a brain dump

Add a CONTRIBUTING file (https://github.com/blog/1184-contributing-guidelines) which explains:

• the LICENSE
• the infrastructure (issue tracker, wiki etc. #7)
• ...

The documentation should mention that Quake 3 itself is poorly documented and link to helpful ressources such as:

• http://fabiensanglard.net/quake3/
• https://www.icculus.org/~phaethon/q3mc/skel.html
• http://www.soclose.de/q3doc/
• http://wiki.ioquake3.org/
• https://github.com/robo9k/ioq3-doc (shameless plug, not quite helpful yet 😄 )
• ...

As part of the infrastructure issue #7, downloads need to be added.

GitHub releases (https://help.github.com/articles/about-releases) could be built via Travis CI (http://docs.travis-ci.com/user/deployment/releases/) using make dist (see #1).

Right now the Python entry point is hardcoded to q3py_hello:dllentry.

This needs to be configurable, possibly with environment variables per module (#10).

The documentation needs to explain how to configure the entry point and how libpython searches for the Python module, e.g. PYTHONPATH, virtualenv and activate_this.py etc.

Currently there is no mention of the module that q3py is meant for, e.g. one of game, cgame or ui.

The configuration of q3py and code need to be prepared to work as either of the modules and be aware which one it is.

A version number/string, preferably using semantic versioning, needs to be added to:

• the q3py API (both C and Python/Capsule)
• documentation
• manual

Try to find and use an external logging library dependency or drop-in files such as http://vincent.bernat.im/en/blog/2013-bootstrap.c.html

or

• use a q3py prefix for log messages
• use configurable logging levels

etc.

A user manual is required, explaining how to:

• download (which version #2 etc.)
• compile (software dependencies, configuration options etc.)
• install (user permissions, options etc.)
• configure (logging etc.)
• run (config file, enviroment variables etc.)
• use as a library from Python, C, Cython etc. (#3)

The manual should also mention that q3py is targeted at developers, not gamers or server admins.

The manual should be part of the README, the documentation and possibly in a GitHub wiki page as well.

The current test cases do not use Python at all.
Add some test cases that actually use Python code/methods.

While the README (e.g. at 3921525) mentions that

q3py is of no use on its own, a separate Python module is needed to implement the required game logic.

one or more usage examples are required.

This means a hello world snippet, possibly using the mentioned but not completed Cython module , needs to be added to the README and manual/documentation.

• hello world

Furthermore possible usages such as the following should be mentioned:

• Interpret or compile the QVM in Python (LLVM etc.)
• Rewrite the whole (game, cgame, ui) logic in Python
  • Integrate this natively with Big Brother Bot

The Doxygen documentation, manual etc. all need to be generated and published entirely automatically.

Things to consider:

• https://github.com/davisp/ghp-import
• https://readthedocs.org/
• ...