search

jakartaee / specification-committee

Documentation base for Specification Committee guides and process to be published at jakarta.ee via Hugo and git submodules
Eclipse Public License 2.0
8 stars 22 forks source link

Publish Specification Committee resources to the website #13

Open waynebeaton opened 5 years ago

waynebeaton commented 5 years ago

The Jakarta EE Specification Committee would like to publish artifacts from this repository to the website. How do we make this happen?

My understanding is that, specifically (minimally), the process.adoc and operations.adoc need to be available. I expect that these documents will change infrequently.

@starksm64 and @dblevins may have additional requirements.

bshannon commented 5 years ago

By "the website", I assume you mean https://jakarta.ee.

The proposal was to make this entire repository appear somewhere on that web site, perhaps under a jakarta.ee/committees/specification directory, to allow for other committees to likewise publish their content. But let us know if you have a better idea.

waynebeaton commented 5 years ago

Is the content to be published "as is"? It looks like a mixed bag to me; that is, I expect that at least some of the content is intended to be rendered from asciidoc to HTML. Somebody needs define specifically what parts need to be converted and expectations regarding the form of the published artifacts.

bshannon commented 5 years ago

Yes, we're assuming the AsciiDoc content is converted to html, like GitHub Pages does. Is the web site actually backed by GitHub Pages? Does this happen automatically? Or do we need to "build" the site by converting all the content to html offline and then publishing it?

chrisguindon commented 5 years ago

Is the web site actually backed by GitHub Pages? Does this happen automatically?

At the moment, we are hosting jakarta.ee via github pages but that could change in the future if we need to update our requirements as we grow.

Does this happen automatically? Or do we need to "build" the site by converting all the content to html offline and then publishing it?

I am currently deploying jakarta.ee via travis-ci+github pages: https://github.com/jakartaee/jakarta.ee/blob/src/.travis.yml

We automatically re-build the website with travis-ci each time a commit is merged into the "src" branch and we commit the output of the "hugo" command to the "master" branch.

Our github pages configuration is setup to serve content from our "master" branch:

https://github.com/jakartaee/jakarta.ee/tree/master

bshannon commented 5 years ago

So, to answer the original question, *.adoc files in the specifications repository will be rendered as html automatically by GitHub Pages on the jakarta.ee web site, right?

chrisguindon commented 5 years ago

So, to answer the original question, *.adoc files in the specifications repository will be rendered as html automatically by GitHub Pages on the jakarta.ee web site, right?

Considering the current state of this repo and the jakarta.ee website repo, github pages will not automatically render the *.adoc files from this repo on the jakarta.ee website.

I believe with a bit of work it would be possible to automate this process. I think we would need to build something similar to how we are publishing the specifications repo on the jakarta.ee website.

I did a bit of research last week when @paulbuck first approached me about publishing content from this repo to the jakarta.ee website and it seems that Hugo does support *.adoc files: https://gohugo.io/content-management/formats/#additional-formats-through-external-helpers

For example, for Asciidoc files, Hugo will try to call the asciidoctor or asciidoc command. This means that you will have to install the associated tool on your machine to be able to use these formats. (See the Asciidoctor docs for installation instructions).

...but it's not clear to me how well these pages are going to render on jakarta.ee in their current state.

If we want to keep things simple, we should convert these *.adoc files to markdown and/or migrate these files to the jakarta.ee repository.

Otherwise we need to try converting .adoc files with hugo to help us identify what we would need to change or build to make this work.