As I recall, the current documentation setup has the documentation in a repository separate from the code. Maven has a plugin called "site" that will generate HTML from markdown and a few other formats and merge it with the javadoc into a single site. In this case the site markdown and such is found under /src/site
My understanding is the Pelican component from Infra will also accept the site structure and output from maven to create the published site. I prefer the site strategy because the documentation is with the source code. So it is easy to verify and make changes when the code is changed. It also means that you can build the site from the code checkout. The maven plugin also lets you "run" the site without deploying it, making it easy to verify changes as well as look and feel. The issue with this approach is that the site is rebuilt during a build, it does not have to be deployed but it is built. This takes extra resource from the Infra build systems and so has an impact there. It also means that fixing typos and similar items in the production site might be more difficult as the site would have to be regenerated (I think). We might need more discussion with Infra to resolve this so we can understand exactly what impact various process changes have on our ability to update documentation without a release and how they recommend the system be setup. Claude On Wed, Sep 11, 2019 at 9:20 PM Andy Seaborne <a...@apache.org> wrote: > > > On 11/09/2019 19:42, Claude Warren wrote: > > I was just speaking to infra about this. Will write more in depth later. > > But we should think about how we want to work. > > > > I favor adding the specific docs to src/site and working from there but I > > am certain there are lots of opinions here. > > I don't know what that means. Could you expand that a bit please? > > Andy > > > > > Claude > > > > On Wed, Sep 11, 2019, 08:35 Andy Seaborne (Jira) <j...@apache.org> > wrote: > > > >> > >> [ > >> > https://issues.apache.org/jira/browse/JENA-1755?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16927696#comment-16927696 > >> ] > >> > >> Andy Seaborne commented on JENA-1755: > >> ------------------------------------- > >> > >> And we need to think about migrating to e.g. Jekyll. > >> > >> I think that new services from INFRA means we can setup a job to > automate > >> the website staging. > >> > >> [ > >> > https://cwiki.apache.org/confluence/display/INFRA/.asf.yaml+features+for+git+repositories > >> ] > >> > >> "automate web site builds using pelican (and other systems)" > >> > >> I haven't had time to dig into the details. > >> > >>> Improve documentation of Query Builders > >>> --------------------------------------- > >>> > >>> Key: JENA-1755 > >>> URL: https://issues.apache.org/jira/browse/JENA-1755 > >>> Project: Apache Jena > >>> Issue Type: Improvement > >>> Reporter: Jan Martin Keil > >>> Priority: Major > >>> > >>> As discussed in JENA-1751, I propose to improve the documentation of > the > >> query builders: > >>> {quote}Unfortunately, I did not find (and I think there isn't) any > >> documentation or tutorial about the query builders explaining more than > the > >> very basics. Also the JavaDoc (which is to the best of my knowledge > nowhere > >> linked on [https://jena.apache.org/]), is, in my experience, not > helpful > >> and makes it often necessary to look into the code to understand what is > >> needed and maybe find out how to get it. If I did not miss a > comprehensive > >> documentation somewhere, I think it would be worth, to improve > >> documentation. Even a few words at the builder classes (mentioning e.g. > >> ExprFactory) and small examples at the more complicated methods would > help > >> a lot. > >>> {quote} > >> > >> > >> > >> -- > >> This message was sent by Atlassian Jira > >> (v8.3.2#803003) > >> > > > -- I like: Like Like - The likeliest place on the web <http://like-like.xenei.com> LinkedIn: http://www.linkedin.com/in/claudewarren
