Hi Andy,
2012/12/5 Andy Seaborne <a...@apache.org> > On 05/12/12 16:42, Sebastian Schaffert wrote: > >> 2012/12/5 Fabian Christ <christ.fab...@googlemail.com> >> >> 2012/12/5 Sebastian Schaffert <sschaff...@apache.org> >>> >>> Regarding the website we have our designer already working on a logo, >>>> >>> and I >>> >>>> suggest we use "mvn site" to automatically generate it, because this >>>> will >>>> already create a lot of documentation. >>>> >>>> >>> So you do not plan to use the Apache CMS [1] for the website? Or do you >>> plan to generate things from Maven for the Apache CMS? >>> >>> It is just a question. I have no experience in generating complete >>> websites >>> from Maven or how to combine it with the ASF CMS. Would be nice to see. >>> >>> >> Many projects already do this. If the Maven "site" reporting is configured >> properly in the Maven build file, this can generate very good and >> extensive >> web pages for a project. The Maven site itself is a good example ( >> http://maven.apache.org/). >> >> The advantage of this approach is that we would not need to maintain >> documentation and source code separately, and it is easy to include >> automatically generated documentation parts like the Javadoc, REST API, >> License Report, or Developer Information in the web page. >> >> So I would try going this approach. :-) >> >> Greetings, >> >> Sebastian >> >> >> >> [1] http://www.apache.org/dev/cms.**html<http://www.apache.org/dev/cms.html> >>> >>> -- >>> Fabian >>> http://twitter.com/fctwitt >>> >>> >> > </mentor> > > The website has two distinct faces : inward to the project and it's > processes, and the maven plugins are good at doing this with reports, but > also outward to users for documentation and maven really does not do much > for that aspect in my experience. > > In a separate site, there is some stuff that needs to be kept in step with > versions but, with careful writing, it's not very much. > > The outward facing documentation, and I mean more than just javadoc, often > has a different lifecycle than the inward-looking project reports. > Of course. I did not mean that the default configuration of "mvn site" should replace a proper webpage (it is a more-or-less useless listing of facts). But properly configured, it is possible to let maven create the complete webpage with proper documentation using a kind-of markup language. The advantage I see is just the one mentioned in the link you sent: you keep the documentation close to the code. > > CMS is great for maintenance - read the website, see something to fix, > press "edit" and do it there and then in the browser. The bulk content is > markdown+tables. > > It may be possible to combine - look at other projects and ask them if > they look interesting. > Agreed. I am not completely fixed on "mvn site", it just looked like a good approach to me. ;-) Greetings, Sebastian
