[jira] [Comment Edited] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16835545#comment-16835545 ] Andy Jefferson edited comment on JDO-779 at 5/9/19 6:18 AM: FWIW DataNucleus uses Asciidoc / Asciidoctor to generate it's documentation. See [http://www.datanucleus.org:15080/products/accessplatform_5_2/] See [https://asciidoctor.org/docs/user-manual/] That operates on Asciidoc files (see [https://github.com/datanucleus/docs-accessplatform/tree/master/src/main/asciidoc] for examples of this format), has a Maven plugin, and generates HTML(5) and/or PDF (as well as other things if you want to go there). Many other Apache projects use that (e.g ISIS, TomEE). was (Author: andy): FWIW DataNucleus uses Asciidoc / Asciidoctor to generate it's documentation. See [http://www.datanucleus.org:15080/products/accessplatform_5_2/] See [https://asciidoctor.org/docs/user-manual/] That operates on Asciidoc files (but maybe also allows input of Markdown?), has a Maven plugin, and generates HTML and/or PDF (as well as other things if you want to go there). Many other Apache projects use that (e.g ISIS, TomEE). > Migrate JDO Homepage / Online Documentation > --- > > Key: JDO-779 > URL: https://issues.apache.org/jira/browse/JDO-779 > Project: JDO > Issue Type: Improvement > Components: site and infrastructure >Reporter: Tilmann Zäschke >Assignee: Tilmann Zäschke >Priority: Major > > The homepage and online documentation is currently generated from xdoc (Maven > 1 doc format), located in the SVN 'site' repo. Te homepage and documentation > should be migrated to a more modern format, such as markdown, and moved to a > new repo. > Initial investigation: > * The only xdoc converter I found is > [Doxia|http://maven.apache.org/doxia/doxia-tools/doxia-converter/]. I don't > really know all the output formats, but one option may by (x)html. This maybe > useful because there exist many html to markdown converters. > * If we use 'html' as intermediate stage, it probably makes sense to > directly migrate the html version of the home page to markdown. > * There are many thml to markdown converters, such as [this PHP command line > converter|https://github.com/thephpleague/html-to-markdown]. > TODO: > # Decide on target repo and create it. Consensus appears to be to set up a > separate git repo, such as 'db-jdo-site'. Where do other projectys host their > website code? > # Decide on conversion path and target format (html -> markdown seems fine) > # Migration -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Comment Edited] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16835545#comment-16835545 ] Andy Jefferson edited comment on JDO-779 at 5/8/19 5:06 PM: FWIW DataNucleus uses Asciidoc / Asciidoctor to generate it's documentation. See [http://www.datanucleus.org:15080/products/accessplatform_5_2/] See [https://asciidoctor.org/docs/user-manual/] That operates on Asciidoc files (but maybe also allows input of Markdown?), has a Maven plugin, and generates HTML and/or PDF (as well as other things if you want to go there). Many other Apache projects use that (e.g ISIS, TomEE). was (Author: andy): FWIW DataNucleus uses Asciidoc / Asciidoctor to generate it's documentation. See [http://www.datanucleus.org:15080/products/accessplatform_5_2/] See [https://asciidoctor.org/docs/user-manual/] That operates on Markdown files, has a Maven plugin, and generates HTML and/or PDF (as well as other things if you want to go there). Many other Apache projects use that (e.g ISIS, TomEE). > Migrate JDO Homepage / Online Documentation > --- > > Key: JDO-779 > URL: https://issues.apache.org/jira/browse/JDO-779 > Project: JDO > Issue Type: Improvement > Components: site and infrastructure >Reporter: Tilmann Zäschke >Assignee: Tilmann Zäschke >Priority: Major > > The homepage and online documentation is currently generated from xdoc (Maven > 1 doc format), located in the SVN 'site' repo. Te homepage and documentation > should be migrated to a more modern format, such as markdown, and moved to a > new repo. > Initial investigation: > * The only xdoc converter I found is > [Doxia|http://maven.apache.org/doxia/doxia-tools/doxia-converter/]. I don't > really know all the output formats, but one option may by (x)html. This maybe > useful because there exist many html to markdown converters. > * If we use 'html' as intermediate stage, it probably makes sense to > directly migrate the html version of the home page to markdown. > * There are many thml to markdown converters, such as [this PHP command line > converter|https://github.com/thephpleague/html-to-markdown]. > TODO: > # Decide on target repo and create it. Consensus appears to be to set up a > separate git repo, such as 'db-jdo-site'. Where do other projectys host their > website code? > # Decide on conversion path and target format (html -> markdown seems fine) > # Migration -- This message was sent by Atlassian JIRA (v7.6.3#76005)
