Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [iot-wg] documentation example
Just a few examples on how we can integrate building static sites using Maven.


An example of how Artemis and Camel projects call gitbook during release process

https://github.com/apache/activemq-artemis/blob/master/artemis-website/pom.xml#L131

We can also use AsciiDoctor and use the maven plugin 

https://github.com/asciidoctor/asciidoctor-maven-plugin

There’s a bunch of example here 

https://github.com/asciidoctor/asciidoctor-maven-examples


On Thu, Nov 10, 2016 at 1:36 PM, Jens Reimann <jreimann@xxxxxxxxxx> wrote:
Thanks Marco!

I also do think that multi-version documentation generation is a necessary feature. And that the current "gh-pages" branch approach is a bit limiting/awkward.

So if we would have some automated system, which takes a Git repository, processes relevant branches and renders those documents in a way that they can be hosted on an HTTP server, then we would have a solution?

When it comes to templating, I think Eclipse IoT could provide a default template which project can either ditch or customize.

Now I am just brainstorming ...

If we would have some sort of Maven plugin, which takes an input file for a project and renders out (using other tools) a full set of documenation for all branches of a project, using some template, then we could simple render this is a local directory which "docs.eclipse.org" would pick up. Such a job could run on "HIPP" instances and re-use the file permissions of the Eclipse infrastructure. If the plugin is smart enough, it will generate documentation for each branch and render this is in sub-directories like "doc.eclipse.org/kura/2.1.0".

On Thu, Nov 10, 2016 at 1:24 PM, Kai Kreuzer <kai@xxxxxxxxxxx> wrote:
We thought it should be possible to have a CI job push a released version

This was also our main idea for not going directly for Github Pages, but generating the HTML throughh Jekyll ourselves.

Kai


On 10 Nov 2016, at 13:14, Brad Micklea <bmicklea@xxxxxxxxxxx> wrote:

@Jens in my original note I'd included the link to the Che docs but people get to it from the Che site, not by surfing readme.io directly: https://eclipse-che.readme.io/docs/

Of course it isn't ideal having a completely foreign URL for docs. That's one of the reasons (plus making it easier for devs to add docs as part of a PR) that we're moving to docs on github + Jekyll. I'm glad to hear that it's working well for others. 

We've been trying to figure out a solution to hosting multiple docs versions with GH/Jekyll. We thought it should be possible to have a CI job push a released version to:


And a separate job push nightly changes to:


This should give us current release docs separated from to-be-released which is enough for us. But theoretically if you needed more versions you could have the CI job simultaneously release docs to:


And


So you'd build up a set of named older version docs.

Brad


On Thursday, 10 November 2016, Carrer, Marco <marco.carrer@xxxxxxxxxxxx> wrote:
What Kura currently does seems like the right approach to me. Hosting content at their GitHub repository, using jekyill to render, hosting on github.io. But you could also just host is somewhere else. The content format is Markdown, which every GitHub user knows. You can fully customize the theming, but keep it separate of the content. So this can be re-used as well.

It is certainly a good start. 

I see few lacking features compared to a solution like read.io:

- github.io will only render the documentation of the latest release - you cannot go back to the documentation of the previous release
- there is no out-of-the-box solutions for readers feedback and suggestions
- swagger support for integrated API documentation
- it is a bit more complicated to set-up and have a professional looking template

Another option to through in the mix is the Jekyll Documentation Theme available here:


Regards,
-Marco



On Nov 10, 2016, at 10:10 AM, Jens Reimann <jreimann@xxxxxxxxxx> wrote:



Hi,

that it was not possible to host such a documentation outside of readme.io.

Do I understand it right, that not even the „sources“ of the documentation are on Github, but only maintained at readme.io? If so, that would also be a no-go for me.

No, what I meant was: readme.io is rendering the documentation, as a service. However you cannot replicate that process outside of readme.io in the same way.

On the other hand I wasn't able to actually find the Eclipse Che documentation. Surely it must be somewhere, and I it was just me. But having a look at readme.io and trying to find out how it works is kind of tricky. It seems you can't even find some sort of documentation unless you start a 14 days trial.

I do think it is a fine tool. Just not the right one for open source projects.

Right now every Eclipse project does have a static homepage available (with some sort of PHP), stored in a Git repository. Wouldn't it be an idea to extend this approach with some sort of page rendering pipeline? So that you check in your documentation to that Git repository and the rendering pipeline rebuilds that homepage and hosts it. There are a few rending pipelines available, such as AsciiDoc, Jekyll, … which could do the task. Maybe even create a domain "docs.eclipse.org" where this all happens.

I think most documentations setups are split up: 1) content storage, 2) rendering pipeline, 3) hosting

1) Should be Git repositories, Hosted at Eclipse (or Eclipse GitHub) IMHO
3) Could be Eclipse infrastructure, but it should be possible to easily host this outside of Eclipse

And 2) is probably the tricky part ;-)

What Kura currently does seems like the right approach to me. Hosting content at their GitHub repository, using jekyill to render, hosting on github.io. But you could also just host is somewhere else. The content format is Markdown, which every GitHub user knows. You can fully customize the theming, but keep it separate of the content. So this can be re-used as well.

So what do you think is missing or could be improved?

Cheers

Jens

-- 
Jens Reimann
Senior Software Engineer / EMEA ENG Middleware
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
phone: +49 89 2050 71286
_____________________________________________________________________________

Red Hat GmbH, www.de.redhat.com,
Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Paul Argiry, Charles Cachera, Michael Cunningham, Michael O'Neill
_______________________________________________
iot-wg mailing list
iot-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/iot-wg



-- 

Brad Micklea | Operations | bmicklea@​codenvy.​com | 4​16​.7​07​.07​92

_______________________________________________
iot-wg mailing list
iot-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/iot-wg


_______________________________________________
iot-wg mailing list
iot-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/iot-wg



--
Jens Reimann
Senior Software Engineer / EMEA ENG Middleware
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
phone: +49 89 2050 71286
_____________________________________________________________________________

Red Hat GmbH, www.de.redhat.com,
Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Paul Argiry, Charles Cachera, Michael Cunningham, Michael O'Neill

_______________________________________________
iot-wg mailing list
iot-wg@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/iot-wg



--
Regards
--
Dejan Bosanac
about.me/dejanb

Back to the top