[jira] [Commented] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17084299#comment-17084299 ] Craig L Russell commented on JDO-779: - Infra suggests using this as a model: https://cwiki.apache.org/confluence/display/INFRA/How+Apache+Jena+migrated+from+the+CMS > 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 (v8.3.4#803005)
[jira] [Commented] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17080357#comment-17080357 ] Andy Jefferson commented on JDO-779: Well done on getting the web site migration going. Some comments in case you want to take them on board. # All pages currently seem to have artifacts in the "title" of the page, shown on the browser tab page name, like # Why do all pages have the Apache JDO logo plus Java Data Objects image? Makes perfect sense to have it on the main entry page, but you have the header area for common things. # Menu options could do with making more compact. e.g JDO Usage has "Implementations" ... put that under the previous menu, and indeed put I'd probably put the whole "JDO Implementation" items under "General". # "JDO Usage" menu option could be merged into a guide for using JDO rather than having a series of small pages like now. See the DN docs for say v5.2 for an example. There is a "guide" for Mapping, and a guide for "Persistence" and so on ... and just bundle all pages into a document. The whole point of having the (right hand) side options was to allow to navigate through a document, so if you have that enabled, then make your doc pages a document with a lot more in them, rather than a series of small pages (where no side navigation would be needed). If you do this then the "JDO Usage" menu will have way fewer items and be much more manageable. Hope that helps > 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 (v8.3.4#803005)
[jira] [Commented] (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 commented on JDO-779: 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)
[jira] [Commented] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16830447#comment-16830447 ] Craig L Russell commented on JDO-779: - The new gitbox/github repo db-jdo-site has been set up and is ready for content. > 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] [Commented] (JDO-779) Migrate JDO Homepage / Online Documentation
[ https://issues.apache.org/jira/browse/JDO-779?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16803171#comment-16803171 ] Craig L Russell commented on JDO-779: - We should use self-service to create a new gitbox repository db-jdo-site that is linked to github and contains the "current contents" of the svn repo jdo/site. We then copy some files directly like the README files and use a more current mvn plugin to generate the site from markdown and then use infra tools to publish the site. > 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)
