You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@isis.apache.org by "Dan Haywood (JIRA)" <ji...@apache.org> on 2015/04/09 09:49:12 UTC
[jira] [Updated] (ISIS-1133) Convert website to asciidoctor, hosted
in git and published via ASF's svnpubsub
[ https://issues.apache.org/jira/browse/ISIS-1133?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dan Haywood updated ISIS-1133:
------------------------------
Description:
Asciidoctor can be found here [1].
Some reasons for doing this:
- the source code for the website will be in git (rather than svn as currently), and so will be mirrored to github. Therefore users/contributors can fork our repo and submit pull requests on the docs/website.
- the generated content can be previewed locally; ASF's svnpubsub infrastructure is used only for publishing/hosting the site
- there are also some doubts about svnpubsub's long-term future, so we should minimize our dependence on it if possible
- the toolchain seems to exist already and is in use by at least one other ASF project - Deltaspike [2] - who have got the toolchain to work. (Wicket are also experimenting, [3])
- the generated pages are themeable either using Foundation (the default) or using Bootstrap .
- github natively understands asciidoc (.adoc) files, and are enthusiastic supporters (see this article of Scott Chacon, [4])
- there are editors for Asciidoctor, eg [5]
- longer term, it's possible that the docs could be converted into a book, eg using O'Reilly's Atlas platform [6]
Good starting points:
- the DeltaSpike pom.xml's. They seem to have two separate regions; the top-level site [7a,7b], and a "documentation" subfolder [8a,8b]
- these use the asciidoctor-maven-plugin [9] to convert the .adoc files to .html
- these use the maven-scm-publish-plugin [10] to update the SVN (do all necessary add/deletes to properly synchronize)
- there are also some useful templates (integrated with mvn site) at [11]
- theming with Bootstrap might be done using any of [12] or [13a, 13b] (latter is asciidoc not asciidoctor so might require some fiddling around with).
[1] http://asciidoctor.org/
[2] http://deltaspike.apache.org/
[3] https://github.com/dashorst/wicketguide
[4] https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
[5] https://github.com/asciidoctor/atom-asciidoc-preview
[6] https://atlas.oreilly.com/
[7a] https://github.com/apache/deltaspike/blob/master/site
[7b] https://github.com/apache/deltaspike/blob/master/site/pom.xml
[8a] https://github.com/apache/deltaspike/tree/master/documentation
[8b] https://github.com/apache/deltaspike/tree/master/documentation/pom.xml
[9] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
[10] https://maven.apache.org/plugins/maven-scm-publish-plugin/
[11] https://github.com/asciidoctor/asciidoctor-maven-examples
[12] https://github.com/nerk/asciidoctor-bs-themes
[13a] https://github.com/llaville/asciidoc-bootstrap-backend
[13b] http://laurent-laville.org/asciidoc/bootstrap/
was:
Deltaspike already do this [1], and Wicket are experimenting [2].
[1] http://deltaspike.apache.org/
[2] https://github.com/dashorst/wicketguide
> Convert website to asciidoctor, hosted in git and published via ASF's svnpubsub
> -------------------------------------------------------------------------------
>
> Key: ISIS-1133
> URL: https://issues.apache.org/jira/browse/ISIS-1133
> Project: Isis
> Issue Type: Improvement
> Components: Website/Other
> Affects Versions: core-1.8.0
> Reporter: Dan Haywood
> Assignee: Dan Haywood
> Fix For: 1.10.0
>
>
> Asciidoctor can be found here [1].
> Some reasons for doing this:
> - the source code for the website will be in git (rather than svn as currently), and so will be mirrored to github. Therefore users/contributors can fork our repo and submit pull requests on the docs/website.
> - the generated content can be previewed locally; ASF's svnpubsub infrastructure is used only for publishing/hosting the site
> - there are also some doubts about svnpubsub's long-term future, so we should minimize our dependence on it if possible
> - the toolchain seems to exist already and is in use by at least one other ASF project - Deltaspike [2] - who have got the toolchain to work. (Wicket are also experimenting, [3])
> - the generated pages are themeable either using Foundation (the default) or using Bootstrap .
> - github natively understands asciidoc (.adoc) files, and are enthusiastic supporters (see this article of Scott Chacon, [4])
> - there are editors for Asciidoctor, eg [5]
> - longer term, it's possible that the docs could be converted into a book, eg using O'Reilly's Atlas platform [6]
> Good starting points:
> - the DeltaSpike pom.xml's. They seem to have two separate regions; the top-level site [7a,7b], and a "documentation" subfolder [8a,8b]
> - these use the asciidoctor-maven-plugin [9] to convert the .adoc files to .html
> - these use the maven-scm-publish-plugin [10] to update the SVN (do all necessary add/deletes to properly synchronize)
> - there are also some useful templates (integrated with mvn site) at [11]
> - theming with Bootstrap might be done using any of [12] or [13a, 13b] (latter is asciidoc not asciidoctor so might require some fiddling around with).
> [1] http://asciidoctor.org/
> [2] http://deltaspike.apache.org/
> [3] https://github.com/dashorst/wicketguide
> [4] https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
> [5] https://github.com/asciidoctor/atom-asciidoc-preview
> [6] https://atlas.oreilly.com/
> [7a] https://github.com/apache/deltaspike/blob/master/site
> [7b] https://github.com/apache/deltaspike/blob/master/site/pom.xml
> [8a] https://github.com/apache/deltaspike/tree/master/documentation
> [8b] https://github.com/apache/deltaspike/tree/master/documentation/pom.xml
> [9] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
> [10] https://maven.apache.org/plugins/maven-scm-publish-plugin/
> [11] https://github.com/asciidoctor/asciidoctor-maven-examples
> [12] https://github.com/nerk/asciidoctor-bs-themes
> [13a] https://github.com/llaville/asciidoc-bootstrap-backend
> [13b] http://laurent-laville.org/asciidoc/bootstrap/
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)