Documentation update - Githubissues

valum-framework / valum

Web micro-framework written in Vala

https://valum-framework.readthedocs.io/en/latest/

GNU Lesser General Public License v3.0

226 stars 23 forks source link

Documentation update #161

Closed arteymix closed 7 years ago

arteymix commented 8 years ago

The documentation is a little behind the changes in the 0.3 series.

Here's a summary of what's not fully covered:

[x] rule system (optional, groups, etc...)
[x] separate concerns among router.rst and route.rst
[x] typed parameters
[x] context
[ ] installation procedure
[ ] getting started (VSGI is bundled in separate shared libraries)
[ ] recipe for CTPL (since it was removed in #145)
[x] recipe(s) for handling structural complexity (see #162)
[ ] recipe for deploying using systemd (lighttpd has some tips here)
[ ] migration guide from 0.2
[ ] API docs
[x] server options with explicit GVariant types

It would be important to revise API docs and update @since annotations.

arteymix commented 8 years ago

I think that we should embrase Wikipedia style for capitals. Title use actual title case whereas sections use sentence case.

arteymix commented 8 years ago

@Bob131 Would you bother writing nginx configuration sample for SCGI and FastCGI?

Bob131 commented 8 years ago

Sure!

arteymix commented 8 years ago

@Bob131 Thanks! It's really going to help!

Any progress on Valadoc-CI? By the way, the fix was merged in waf, so you can generate the docs with something like:

./waf configure build install VALAFLAGS='--vapi-comments'
valadoc --pkg=valum --deps --target-glib=2.32 --directory=destination

If VAPIs and other build files are versionned by MAJOR.MINOR, it should be possible to install multiple version alongside and generate the docs by specifying --pkg=valum-0.2 --pkg=valum-0.3.

Maybe just generate all the docs for all packages installed on the server? Listing /usr/local/share/vala/vapi would be a good approach I think.

arteymix commented 8 years ago

The migration guide should cover breaking changes:

return value for various callbacks #166
method -> rule in Router
all -> use
flags for HTTP methods
Cookies -> CookieUtils and in-place sign
cookie parsing and lookup has moved into Request and Response
context rather than a stack
shared library per-implementation

arteymix commented 8 years ago

The docs are now much more concise and pleasant to read as of 72c1e56 :)

arteymix commented 8 years ago

Since listen options are serialized in a GLib.Variant, it would be essential to expose what type is used per option.