Module documentation browser

[ahutchings]

Allow users to browse module documentation

[samwilson]

👍

[happyDemon]

I'm willing to work on this, what would be the best option though? Import the documentation files to the server or always load them from github (I'm not sure on how many api requests are allowed a day).

[happyDemon]

How about we import the user guide to the database when a module's imported the first time.

Every time a new release is tagged we'd do another import of the user guide, or if kohana-modules would support github-hooks we could import the guide if a change to it was made (periodically importing the guides of all modules seems a bit overkill).

[ahutchings]

I think importing to the database along with the module data is the way to go also. GitHub hooks would be my preferred update method if we have access to the hooks required, if not we could fall back to the site's existing module-syncing cron script to refresh docs.

What do you think about embedding the docs in the page vs. serving them via a username/modulename/docs route or something similar?

[happyDemon]

Where would we add the guide menu?

I guess the top link in the menu could be called info (with mod-info as slug or something) and show the current module page, where the guide's links would be kept intact (e.g. kohana-modules.com/modules///).

I think I'm going to have fun with this on sunday ^^

[happyDemon]

I was thinking, to spare the github api requests being made, it might be best to download the master zipball of a repo, unpackage it, read out the userguide, import it to the database and then delete the files along with zip file.

[ahutchings]

How do you plan to store the docs? They aren't generated HTML, and must be served through the userguide module, so we may end up having to store them on disk after all instead of storing them in the database. Also, the userguide module uses reflection to generate the module API docs, so we may need the full module tarball on disk instead of just the guide directory.

What do you think about supporting multiple versions of docs for each module? 3.2 docs, 3.3 docs, etc. This could be a non-trivial task, since if we're required to serve the docs through the userguide module, we'd need multiple versions of Kohana running.

The kohana-modules repo itself may end up being helpful in solving both problems, since we could spin up multiple Kohana apps, each serving docs for a different branch of kohana-modules modules.

[happyDemon]

I was thinking of simply using and tweaking the userguide's kmarkdown parser to fit our needs to serve the guide pages and scrape and store the API pages so the API links wouldn't break.

Supporting multiple versions sounds, good ^^

Your solution might be simpler though and save a lot of headache xD

[ahutchings]

If we support multiple versions, we may be required to use an API-compatible version of userguide to scrape and/or serve the guides. Not sure how much the userguide API has changed, but I think matching the versions would be the safest route.

I'd like to avoid the complexity of having multiple Kohana apps running simultaneously, but I'm not sure if that's possible. Given the amount of work this will likely take, it may not be worth it to serve guides for all versions - let's start with whatever you feel like tackling and we'll go from there.

[happyDemon]

For the next pull request I've been able to store the 'master' userguide for repos in the database and serve them through kohana-modules.com/$username/$module/guide(/$page).
In the future we could tweak it to store the userguide for all tagged releases. But for now Ithink this might do.
I haven't been able to figure out how we could optimally serve the API docs though.