One of the largest complaints with FreeRADIUS is the lack of comprehensive documentation.
The previous wiki has served its purpose, but has ultimately failed to provide an up-to-date, well organised source of documentation.
The major problems with the previous wiki were:
- spam users - which meant we had to lock registration, and discouraged new users from contributing
- exporting information - all pages are stored in an sql lite instance, which made it hard to automatically roll pages into releases
- formatting information - Information stored in the wiki was/is in the Media wiki format, whereas the documentation bundled with FreeRADIUS is either unformatted or in rst format.
To try and solve these issues and glue everything together a bit more, we setup this new wiki based on Gollum. Gollum is a ruby on rails application which exposes a git repository as wiki site. Gollum can render files in many markup languages including plaintext, RST and Mediawiki format, which means we can import all current server documentation, all current wiki documentation and have them neatly presented in a single wiki site. Neat huh?
But what about spam and registration? Well by default gollum doesn't authenticate anyone. But because it's a rails application we can drop in a library called 'OmniAuth' which uses Oauth to authenticate a bunch of providers.
This allows us to leverage authentication and spam account prevention services of providers like GitHub, Facebook and Twitter.
Unfortunately the new wiki needs some fixes. The mediawiki page format renderer in gollum isn't perfect, so we need to convert the pages which don't render correctly to RST as a priority.
If you want to help out, please do the following:
- Sign up for Facebook, Twitter or GitHub
- Pick a page where the MediaWiki format doesn't render correctly
- Click the 'Edit page' button
- Change edit mode from MediaWiki to reStructuredText or <arkdown
- Convert markup to reStructuredText or Markdown (Cheat sheet)
- Save the page
- Get warm fuzzy glow from contributing to open source
Also please report any bugs here:
gollum issue tracker
- Last commit for pages reflect the last person to commit to the repo
- Markdown pages don't display TOC, this is a upstream bug in the 1.3.0 version of gollum
- No delete or rename functionality, this is a upstream bug in the 1.3.0 version of gollum
- When creating pages, you are only prompted to login after attempting to submit modifications; this is somewhat of a design flaw in gollum, not specifying a get url for creating pages. A workaround will be written and implemented soon.
Pages that need converting as a priority (please mark here when converted)
Pages to convert to markdown
Pages to convert to RST
- Enable renaming wiki pages - JC
- Fix external links - Arran CB - Done 31/05/11 (see here https://github.com/github/gollum/pull/166)
- Fix per page committer info - Arran CB - Done 22/06/11
- Add google as omniauth provider - Arran CB
- Implement proper fix for page creation - Arran CB - Done 20/06/11
- Fix TOC for markdown pages - Arran CB - Done 20/06/11
- Set up anonymous git access for wiki - Alan D
- Set up commit log to user mailing list - Alan D