I believe we are close to completion as far as existing documentation goes. There may be 1 or 2 areas that still need more write-up and polish but for the most part, docs are looking good. Some automation may be in order.
I wanted offer some suggestions on managing javadocs and versioning of the documentation: - On javadocs, I think we can simply generate the docs on the master branch and move them over to a javadocs directory of the gh-pages branch. I think that should render just fine and we should be able to automate the process to some degree. Javadocs would be updated at release time when the API would freeze so this really for the most part becomes a one-time task. - On versions, since branching doesnt quite work with github pages it might make sense to move everything under a previous directory of some sort, and create a structure that matches each version. Something like previous\4.0, previous\4.1, etc. The contents of the root would always contain documentation for the version in development and will be moved to the right folder at release time, and I suppose we could provide some sort of dropdown on the main page to allow folks to navigate between doc versions. Does that make sense? From: Misagh Moayyed [mailto:[email protected]] Sent: Monday, January 20, 2014 7:36 AM To: [email protected] Subject: RE: [cas-dev] CAS 4.0 Documentation Sure. I need to make a few improvements so its able to detect existing anchor tags first and then of course, we can automate the process. As far as Jekyll, see if the following notes help: https://github.com/jasig/cas/tree/gh-pages#troubleshooting I am intentionally using 1.4.2 to bypass a bug that looks like would be in v2. Misagh From: Jérôme LELEU [mailto:[email protected]] Sent: Monday, January 20, 2014 2:54 AM To: [email protected] Subject: Re: [cas-dev] CAS 4.0 Documentation Hi, Could this Groovy script be integrated somehow in the process? I'm always doutbful when it comes to manual operations: it's so easy to forget. Two more comments about documentation: - I've tried to use jekyll on Windows and after a fierce struggle, I gave up on using it (whereas it works perfectly on my Ubuntu station) - reading again the spec, I didn't find any mention of the front SLO: was it meant on purpose? Thanks. Best regards, Jérôme 2014/1/18 Misagh Moayyed <[email protected]> JIRA tracking documentation tasks: https://issues.jasig.org/browse/CAS-1417 Misagh _____ From: "Misagh Moayyed" <[email protected]> To: [email protected] Sent: Friday, January 17, 2014 1:53:06 PM Subject: Re: [cas-dev] CAS 4.0 Documentation I realized the pages dont automatically generate anchor tags for section headers, like the wiki. This is useful for TOCs to provide direct links to a section. Rather than doing this manually, I put together a small groovy script that auto-generates these tags: https://github.com/mmoayyed/markdown-anchors There are a few quirks to be worked out wrt to unicode characters, but in general, works great. Misagh _____ From: "Robert Oschwald" <[email protected]> To: [email protected] Sent: Friday, January 17, 2014 8:55:10 AM Subject: Re: [cas-dev] CAS 4.0 Documentation This anchors are used by Pandoc to generate the TOC in the final Spec PDF. Am 17.01.2014 um 16:49 schrieb Jérôme LELEU <[email protected]>: Hi, I'm currently seeing a lot of anchors in the markdown files. For example: <a name="AuthenticationManager"> </a> ######`AuthenticationManager` Is it normal? What's the use of this anchor in addition to the title below? Thanks. Best regards, Jérôme 2014/1/15 Misagh Moayyed <[email protected]> Fair point, the new coloring is pretty difficult on the eye. I am no CSS expert, but I will see if I can just pull in the relevant CSS classes for alerts. That should restore the theme to be not as much screamish :) Misagh -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev
