help with site migration

[Ioan Eugen Stan <st...@gmail.com>]

Hello,

I need to gather some info about the site migration. I've put up a JIRA 
so please add your comments there [1].

I'm wish to make a list of all the moving parts so I can figure out how 
to put them together.

Please feel free to add info about how docs are generated and published. 
 From what I know we use maven site plugin to generate the docs from 
some xml pages.

The site from server get's published at ${james.url}/server/3; similar, 
the site for mailbox get's published at ${james.url}/mailbox.

Besides the wiki and this, is there anything else that generates docs?

I also wish to move to a more friendlier way of writing docs (something 
with Markdown syntax maybe, I don't know). This may imply moving away 
from mvn site. How do you feel about this?

[1] https://issues.apache.org/jira/browse/JAMES-1398

Thanks,
-- 
Ioan Eugen Stan
http://ieugen.blogspot.com

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org

Re: help with site migration

[Stefano Bagnara <ap...@bago.org>]

2012/4/3 Ioan Eugen Stan <st...@gmail.com>:
> "Much more pages using plugins" means the maven reports?

Yes. There are a lot of "kind" of maven reports.
javadocs and xrefs are additional pages not directly "generated" by
maven (only orchestrated/aggregated by maven)
then there are standard maven reports and other reports like coverage,
PMD, dependencies..

> We agree on consistency and ease of use. I don't know any solution by
> now but I'm going to ask around and see how others have switched and
> what worked for them.
>
> Thanks for the input, Stefano.

Thanks to you for doing things!
Stefano

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org

Re: help with site migration

[Ioan Eugen Stan <st...@gmail.com>]

2012/4/3 Stefano Bagnara <ap...@bago.org>:
> 2012/4/2 Ioan Eugen Stan <st...@gmail.com>:
>> Please feel free to add info about how docs are generated and published.
>> From what I know we use maven site plugin to generate the docs from some xml
>> pages.
>
> Maven generates some page using the xdoc format and files we put in
> the /src/site folder of each project. Then it also generate much more
> pages using plugins.

"Much more pages using plugins" means the maven reports?

> There is a lot of stuff we generate using maven and that you can't
> generate otherwise, so we'll still need maven to update the website.

If you're not referring to the maven report generation please give me
some examples so I know what you mean.

>> I also wish to move to a more friendlier way of writing docs (something with
>> Markdown syntax maybe, I don't know). This may imply moving away from mvn
>> site. How do you feel about this?
>
> I don't care about syntax, but I care about consistency and easyness
> of the release process, so I expect you to show us some proposal in a
> sandbox so we can have a look at it and its workflow.
> And if you want to move to something different from the current xdocs
> you should prepare to "translate" all of our projects (otherwise we
> end up with 2 different ways to do things and in the long term this
> gives nothing good).
>
> Stefano
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
> For additional commands, e-mail: server-dev-help@james.apache.org
>

We agree on consistency and ease of use. I don't know any solution by
now but I'm going to ask around and see how others have switched and
what worked for them.

Thanks for the input, Stefano.

Regards,
-- 
Ioan Eugen Stan
http://ieugen.blogspot.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org

Re: help with site migration

[Stefano Bagnara <ap...@bago.org>]

2012/4/2 Ioan Eugen Stan <st...@gmail.com>:
> Please feel free to add info about how docs are generated and published.
> From what I know we use maven site plugin to generate the docs from some xml
> pages.

Maven generates some page using the xdoc format and files we put in
the /src/site folder of each project. Then it also generate much more
pages using plugins.
There is a lot of stuff we generate using maven and that you can't
generate otherwise, so we'll still need maven to update the website.

> I also wish to move to a more friendlier way of writing docs (something with
> Markdown syntax maybe, I don't know). This may imply moving away from mvn
> site. How do you feel about this?

I don't care about syntax, but I care about consistency and easyness
of the release process, so I expect you to show us some proposal in a
sandbox so we can have a look at it and its workflow.
And if you want to move to something different from the current xdocs
you should prepare to "translate" all of our projects (otherwise we
end up with 2 different ways to do things and in the long term this
gives nothing good).

Stefano

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org