Hi Thanh,

Thanks a lot for the feedback. I pretty much agree with retiring Maven
Sites from our project, as I prefer the look of the Sphinx generated HTML.
However, we do include our Javadoc in the Maven Sites generated
documentation, which is handy. What would be the best way to publish
Javadoc if we disable Maven Sites?


On Wed, Oct 12, 2016 at 9:34 AM, Thanh Ha <thanh...@linuxfoundation.org>

> Hi Everyone,
> Still digging through my emails :)
> Regarding formats supported by the Maven site plugin. It actually uses
> Doxia so supports whatever formats Doxia supports. The support matrix is
> available here:
> https://maven.apache.org/doxia/references/index.html
> I think we should retire the use of Maven Sites though considering it adds
> a significant amount of time to a project build to generate and the Sphinx
> toolchain in my opinion is better and we can run the docs as a separate job
> so the verify and merge job build times remain quick.
> My recommendation would be to just create a docs directory in your project
> and then run `sphinx-quickstart` to initialize your repo. See:
> http://www.sphinx-doc.org/en/stable/invocation.html
> Then we can link it where appropriate in the main docs project if you want
> integration there. We just need to load the project in as a submodule and
> then link the docs to the relative submodule path.
> Thanh
> On Mon, Oct 10, 2016 at 12:34 PM, Lori Jakab <lorand.jakab+...@gmail.com>
> wrote:
>> Hi,
>> Reposting, since Thanh may be back.
>> Meanwhile I had another idea. Alternatively to the maven sites
>> documentation, we could just use directly the new readthedocs infra, since
>> I see that some 'submodules' sites are linked to on the main page. So I
>> guess it may be better to just add the docs the we want to maintain in our
>> own repo to a 'docs' directory and ask for a link on the sphinx main page?
>> Thanks,
>> -Lori
>> On Tue, Oct 4, 2016 at 8:31 PM, Colin Dixon <co...@colindixon.com> wrote:
>>> This would be a really good thing to get in front of Thanh since he's
>>> done most of the work on our maven sites documentation as well as being our
>>> local reST/sphinx expert. He's out on PTO this week.
>>> --Colin
>>> On Tue, Oct 4, 2016 at 8:31 AM, Lori Jakab <lorand.jakab+...@gmail.com>
>>> wrote:
>>>> Hi,
>>>> I've been looking at our in-project maven site documentation, and I see
>>>> that it's using markdown. Quick question: does the build system support
>>>> reStructured Text too? I know it should support Asciidoc, according to [0]
>>>> (which should probably be removed, to discourage new Asciidoc
>>>> documentation) so it's probably just a matter of putting the right content
>>>> in the right place, but I couldn't find any references to reStructuredText
>>>> at [1] (and the Asciidoc support was ODL in-house). How complicated would
>>>> it be for the support to be added, if it's not there yet?
>>>> I'm asking because I think it should be easy to migrate docs from a
>>>> project to docs. Something that starts out as a few notes here and there
>>>> may grow into something that may be useful to be added to the
>>>> Developer/User Guides. Or, those Guides could be generated using content
>>>> from a project's Maven Sites documentation.
>>>> I'm pretty sure this has already been discussed, and I missed it, so
>>>> sorry for the noise.
>>>> -Lori
>>>> [0] https://nexus.opendaylight.org/content/sites/site/org.op
>>>> endaylight.odlparent/carbon/asciidoc-in-site.html
>>>> [1] https://maven.apache.org/plugins/maven-site-plugin/examp
>>>> les/creating-content.html
Discuss mailing list

Reply via email to