[GitHub] tomee pull request #234: TOMEE-2316 Convert Markdown files to Asciidoc in th...

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

[GitHub] tomee pull request #234: TOMEE-2316 Convert Markdown files to Asciidoc in th...

otaviojava
GitHub user cchacin opened a pull request:

    https://github.com/apache/tomee/pull/234

    TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder

    [[TOMEE-2316]](https://github.com/cchacin/tomee/pull/new/TOMEE-2316)
   
    Apologies for the huge PR, this is to migrate the documentation from `markdown` to `asciidoc`
   
    Migrated documentation from Markdown to Asciidoc in two separated commits to make the review a little bit easier:
   
    * Migrating to Asciidoc 1645fc3
    * Deleting the Markdown files 2fdde27
   
    ### **Is this the proper format for the file header❓**
   
    ```ascidoc
    :index-group: General Information
    :type: page
    :status: published
    :title: About the 'tomee' webapp
    ~~~~~~
    ```
   
    <details><h3><summary>List of Changed Files:</summary></h3>
    <p>
   
    ```
    /docs/openjpa.md => /docs/openjpa.adoc
    /docs/spring-and-openejb-3.0.md => /docs/spring-and-openejb-3.0.adoc
    /docs/application-resources.md => /docs/application-resources.adoc
    /docs/basics---getting-things.md => /docs/basics---getting-things.adoc
    /docs/tomee-jaas.md => /docs/tomee-jaas.adoc
    /docs/callbacks.md => /docs/callbacks.adoc
    /docs/local-server.md => /docs/local-server.adoc
    /docs/clients.md => /docs/clients.adoc
    /docs/spring-ejb-and-jpa.md => /docs/spring-ejb-and-jpa.adoc
    /docs/tomee-and-intellij.md => /docs/tomee-and-intellij.adoc
    /docs/constructor-injection.md => /docs/constructor-injection.adoc
    /docs/spring.md => /docs/spring.adoc
    /docs/cmpentitycontainer-config.md => /docs/cmpentitycontainer-config.adoc
    /docs/embedded-configuration.md => /docs/embedded-configuration.adoc
    /docs/custom-injection.md => /docs/custom-injection.adoc
    /docs/property-overriding.md => /docs/property-overriding.adoc
    /docs/arquillian-available-adapters.md => /docs/arquillian-available-adapters.adoc
    /docs/managedcontainer-config.md => /docs/managedcontainer-config.adoc
    /docs/tomee-embedded-maven-plugin.md => /docs/tomee-embedded-maven-plugin.adoc
    /docs/deployments.md => /docs/deployments.adoc
    /docs/openejb-jsr-107-integration.md => /docs/openejb-jsr-107-integration.adoc
    /docs/tomee-and-netbeans.md => /docs/tomee-and-netbeans.adoc
    /docs/hello-world.md => /docs/hello-world.adoc
    /docs/eclipse-plugin.md => /docs/eclipse-plugin.adoc
    /docs/datasource-configuration-by-creator.md => /docs/datasource-configuration-by-creator.adoc
    /docs/basics---security.md => /docs/basics---security.adoc
    /docs/details-on-openejb-jar.md => /docs/details-on-openejb-jar.adoc
    /docs/comparison.md => /docs/comparison.adoc
    /docs/arquillian-getting-started.md => /docs/arquillian-getting-started.adoc
    /docs/multicast-discovery.md => /docs/multicast-discovery.adoc
    /docs/openejb.xml.md => /docs/openejb.xml.adoc
    /docs/common-persistenceprovider-properties.md => properties.adoc
    /docs/multipoint-recommendations.md => /docs/multipoint-recommendations.adoc
    /docs/multipoint-discovery.md => /docs/multipoint-discovery.adoc
    /docs/tomee-maven-plugin.md => /docs/tomee-maven-plugin.adoc
    /docs/tomee-mp-getting-started.md => /docs/tomee-mp-getting-started.adoc
    /docs/documentation.old.md => /docs/documentation.old.adoc
    /docs/tomcat-object-factory.md => /docs/tomcat-object-factory.adoc
    /docs/ejb-over-ssl.md => /docs/ejb-over-ssl.adoc
    /docs/functional-testing-with-openejb,-jetty-and-selenium.md => and-selenium.adoc
    /docs/built-in-type-converters.md => /docs/built-in-type-converters.adoc
    /docs/manual-installation.md => /docs/manual-installation.adoc
    /docs/jndi-names.md => /docs/jndi-names.adoc
    /docs/tip-concurrency.md => /docs/tip-concurrency.adoc
    /docs/singletoncontainer-config.md => /docs/singletoncontainer-config.adoc
    /docs/singleton-beans.md => /docs/singleton-beans.adoc
    /docs/concepts.md => /docs/concepts.adoc
    /docs/provisioning.md => /docs/provisioning.adoc
    /docs/from-glassfish-to-tomee.md => /docs/from-glassfish-to-tomee.adoc
    /docs/securing-a-web-service.md => /docs/securing-a-web-service.adoc
    /docs/local-client-injection.md => /docs/local-client-injection.adoc
    /docs/tomee-version-policies.md => /docs/tomee-version-policies.adoc
    /docs/maven/undeploy-mojo.md => /docs/maven/undeploy-mojo.adoc
    /docs/maven/run-mojo.md => /docs/maven/run-mojo.adoc
    /docs/maven/stop-mojo.md => /docs/maven/stop-mojo.adoc
    /docs/maven/list-mojo.md => /docs/maven/list-mojo.adoc
    /docs/maven/debug-mojo.md => /docs/maven/debug-mojo.adoc
    /docs/maven/help-mojo.md => /docs/maven/help-mojo.adoc
    /docs/maven/deploy-mojo.md => /docs/maven/deploy-mojo.adoc
    /docs/maven/exec-mojo.md => /docs/maven/exec-mojo.adoc
    /docs/maven/index.md => /docs/maven/index.adoc
    /docs/maven/start-mojo.md => /docs/maven/start-mojo.adoc
    /docs/maven/configtest-mojo.md => /docs/maven/configtest-mojo.adoc
    /docs/maven/build-mojo.md => /docs/maven/build-mojo.adoc
    /docs/multipoint-considerations.md => /docs/multipoint-considerations.adoc
    /docs/statefulcontainer-config.md => /docs/statefulcontainer-config.adoc
    /docs/Configuring-in-tomee.md => /docs/Configuring-in-tomee.adoc
    /docs/failover-logging.md => /docs/failover-logging.adoc
    /docs/javaagent-with-maven-surefire.md => /docs/javaagent-with-maven-surefire.adoc
    /docs/lookup-of-other-ejbs-example.md => /docs/lookup-of-other-ejbs-example.adoc
    /docs/changing-jms-implementations.md => /docs/changing-jms-implementations.adoc
    /docs/proxyfactory-config.md => /docs/proxyfactory-config.adoc
    /docs/application-deployment-solutions.md => /docs/application-deployment-solutions.adoc
    /docs/understanding-callbacks.md => /docs/understanding-callbacks.adoc
    /docs/multipulse-discovery.md => /docs/multipulse-discovery.adoc
    /docs/quickstart.md => /docs/quickstart.adoc
    /docs/hibernate.md => /docs/hibernate.adoc
    /docs/properties-listing.md => /docs/properties-listing.adoc
    /docs/ssh.md => /docs/ssh.adoc
    /docs/faq.md => /docs/faq.adoc
    /docs/tip-weblogic.md => /docs/tip-weblogic.adoc
    /docs/bmpentitycontainer-config.md => /docs/bmpentitycontainer-config.adoc
    /docs/embedded-and-remotable.md => /docs/embedded-and-remotable.adoc
    /docs/running-a-standalone-openejb-server.md => /docs/running-a-standalone-openejb-server.adoc
    /docs/service-locator.md => /docs/service-locator.adoc
    /docs/transactionmanager-config.md => /docs/transactionmanager-config.adoc
    /docs/declaring-references.md => /docs/declaring-references.adoc
    /docs/jpa-concepts.md => /docs/jpa-concepts.adoc
    /docs/configuring-durations.md => /docs/configuring-durations.adoc
    /docs/configuring-containers-in-tests.md => /docs/configuring-containers-in-tests.adoc
    /docs/tomee-directory-structure.md => /docs/tomee-directory-structure.adoc
    /docs/javamailsession-config.md => /docs/javamailsession-config.adoc
    /docs/contrib/debug/debug-intellij.md => /docs/contrib/debug/debug-intellij.adoc
    /docs/datasource-config.md => /docs/datasource-config.adoc
    /docs/basics---transactions.md => /docs/basics---transactions.adoc
    /docs/maven.md => /docs/maven.adoc
    /docs/remote-server.md => /docs/remote-server.adoc
    /docs/tomee-webaccess.md => /docs/tomee-webaccess.adoc
    /docs/getting-started.md => /docs/getting-started.adoc
    /docs/installing-tomee.md => /docs/installing-tomee.adoc
    /docs/system-properties.md => /docs/system-properties.adoc
    /docs/initialcontext-config.md => /docs/initialcontext-config.adoc
    /docs/client-server-transports.md => /docs/client-server-transports.adoc
    /docs/persistence-unit-ref.md => /docs/persistence-unit-ref.adoc
    /docs/application-composer/history.md => /docs/application-composer/history.adoc
    /docs/application-composer/getting-started.md => /docs/application-composer/getting-started.adoc
    /docs/application-composer/index.md => /docs/application-composer/index.adoc
    /docs/application-composer/advanced.md => /docs/application-composer/advanced.adoc
    /docs/ejb-request-logging.md => /docs/ejb-request-logging.adoc
    /docs/common-errors.md => /docs/common-errors.adoc
    /docs/javaee7-status.md => /docs/javaee7-status.adoc
    /docs/standalone-server.md => /docs/standalone-server.adoc
    /docs/embedding.md => /docs/embedding.adoc
    /docs/version-checker.md => /docs/version-checker.adoc
    /docs/bouncy-castle.md => /docs/bouncy-castle.adoc
    /docs/activemqresourceadapter-config.md => /docs/activemqresourceadapter-config.adoc
    /docs/validation-tool.md => /docs/validation-tool.adoc
    /docs/tomee-logging.md => /docs/tomee-logging.adoc
    /docs/installation-drop-in-war.md => /docs/installation-drop-in-war.adoc
    /docs/statelesscontainer-config.md => /docs/statelesscontainer-config.adoc
    /docs/resource-ref-for-datasource.md => /docs/resource-ref-for-datasource.adoc
    /docs/configuration.md => /docs/configuration.adoc
    /docs/properties-tool.md => /docs/properties-tool.adoc
    /docs/application-discovery-via-the-classpath.md => /docs/application-discovery-via-the-classpath.adoc
    /docs/persistence-context.md => /docs/persistence-context.adoc
    /docs/annotations,-xml-and-defaults.md => /docs/annotations,-xml-and-defaults.adoc
    /docs/configuring-persistenceunits-in-tests.md => tests.adoc
    /docs/javaagent.md => /docs/javaagent.adoc
    /docs/app-clients-and-jndi.md => /docs/app-clients-and-jndi.adoc
    /docs/multiple-business-interface-hazzards.md => /docs/multiple-business-interface-hazzards.adoc
    /docs/configuring-datasources.md => /docs/configuring-datasources.adoc
    /docs/dynamic-datasource.md => /docs/dynamic-datasource.adoc
    /docs/telnet-console.md => /docs/telnet-console.adoc
    /docs/services.md => /docs/services.adoc
    /docs/understanding-the-directory-layout.md => /docs/understanding-the-directory-layout.adoc
    /docs/startup.md => /docs/startup.adoc
    /docs/deamon/win-service.md => /docs/deamon/win-service.adoc
    /docs/deamon/lin-service.md => /docs/deamon/lin-service.adoc
    /docs/tomee-and-webspheremq.md => /docs/tomee-and-webspheremq.adoc
    /docs/tomee-logging-in-eclipse.md => /docs/tomee-logging-in-eclipse.adoc
    /docs/documentation.md => /docs/documentation.adoc
    /docs/deploy-tool.md => /docs/deploy-tool.adoc
    /docs/deploying-in-tomee.md => /docs/deploying-in-tomee.adoc
    /docs/orb-config.md => /docs/orb-config.adoc
    /docs/messagedrivencontainer-config.md => /docs/messagedrivencontainer-config.adoc
    /docs/configuring-datasources-in-tests.md => /docs/configuring-datasources-in-tests.adoc
    /docs/collapsed-ear.md => /docs/collapsed-ear.adoc
    /docs/resource-injection.md => /docs/resource-injection.adoc
    /docs/openejb-eclipse-plugin.md => /docs/openejb-eclipse-plugin.adoc
    /docs/features.md => /docs/features.adoc
    /docs/ejb-local-ref.md => /docs/ejb-local-ref.adoc
    /docs/openejb-binaries.md => /docs/openejb-binaries.adoc
    /docs/jpa-usage.md => /docs/jpa-usage.adoc
    /docs/deployment-id.md => /docs/deployment-id.adoc
    /docs/unix-daemon.md => /docs/unix-daemon.adoc
    /docs/tip-jersey-client.md => /docs/tip-jersey-client.adoc
    /docs/singleton-ejb.md => /docs/singleton-ejb.adoc
    /docs/security-annotations.md => /docs/security-annotations.adoc
    /docs/ejb-ref.md => /docs/ejb-ref.adoc
    /docs/configuring-logging-in-tests.md => /docs/configuring-logging-in-tests.adoc
    /docs/containers-and-resources.md => /docs/containers-and-resources.adoc
    /docs/tomee-webapp.md => /docs/tomee-webapp.adoc
    /docs/transaction-annotations.md => /docs/transaction-annotations.adoc
    /docs/common-datasource-configurations.md => /docs/common-datasource-configurations.adoc
    /docs/new-in-openejb-3.0.md => /docs/new-in-openejb-3.0.adoc
    /docs/java7.md => /docs/java7.adoc
    /docs/datasource-password-encryption.md => /docs/datasource-password-encryption.adoc
    /docs/installation.md => /docs/installation.adoc
    /docs/queue-config.md => /docs/queue-config.adoc
    /docs/openejb-3.md => /docs/openejb-3.adoc
    /docs/jmsconnectionfactory-config.md => /docs/jmsconnectionfactory-config.adoc
    /docs/ejb-refs.md => /docs/ejb-refs.adoc
    /docs/securityservice-config.md => /docs/securityservice-config.adoc
    /docs/tomee-and-security.md => /docs/tomee-and-security.adoc
    /docs/tomee-and-hibernate.md => /docs/tomee-and-hibernate.adoc
    /docs/ejb-failover.md => /docs/ejb-failover.adoc
    /docs/jms-resources-and-mdb-container.md => /docs/jms-resources-and-mdb-container.adoc
    /docs/alternate-descriptors.md => /docs/alternate-descriptors.adoc
    /docs/configuring-javamail.md => /docs/configuring-javamail.adoc
    /docs/generating-ejb-3-annotations.md => /docs/generating-ejb-3-annotations.adoc
    /docs/security.md => /docs/security.adoc
    /docs/system-properties-files.md => /docs/system-properties-files.adoc
    /docs/ejbd-transport.md => /docs/ejbd-transport.adoc
    /docs/topic-config.md => /docs/topic-config.adoc
    /docs/tomee-and-eclipse.md => /docs/tomee-and-eclipse.adoc
    ```
    </p>

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/cchacin/tomee TOMEE-2316

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/tomee/pull/234.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #234
   
----
commit 1645fc316925c8ae138077f1e634c6bc8fced4ab
Author: Carlos Chacin <cchacin@...>
Date:   2018-12-04T08:08:58Z

    Converting docs/*.md to docs/*.adoc

commit 2fdde2717e54e47c979fa8e42dac56c88a04817d
Author: Carlos Chacin <cchacin@...>
Date:   2018-12-04T08:15:50Z

    Removing markdown files

----


---
Reply | Threaded
Open this post in threaded view
|

[GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

otaviojava
Github user cchacin commented on the issue:

    https://github.com/apache/tomee/pull/234
 
    I'm happy to split this in several PRs if the changes make sense


---
Reply | Threaded
Open this post in threaded view
|

Re: [GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

David Blevins-2
Thank you for the PR, Carlos!

Give this a try with the site generator:

 - https://github.com/apache/tomee-site-generator

JBake defines header for Asciidoc slightly differently than it does for Markdown.  Check out:

 - https://jbake.org/docs/2.6.3/#metadata_header

Specifically, there's no "~~~~~~" terminator and all JBake properties must start with ":jbake-".  Important note that ":index-group:" is fine as that is one of our headers.

The site generator will create a clone of TomEE master in repos/tomee-8.0/.  You can pull your PR into that using this script:

 - https://gist.github.com/dblevins/6e255634d84914beb051a4b3858ebfb4

And then hammer away till it all looks good.

I probably would recommend doing them in batches as you mention in your PR, just because you're scripting this and no one is perfect and each page should be reviewed with a human eye before being merged or going live.  I think one pig PR is a huge time commitment to review in one shot.

Huge thank you for taking this on!!!!


--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Dec 4, 2018, at 1:02 AM, cchacin <[hidden email]> wrote:
>
> Github user cchacin commented on the issue:
>
>    https://github.com/apache/tomee/pull/234
>
>    I'm happy to split this in several PRs if the changes make sense
>
>
> ---

Reply | Threaded
Open this post in threaded view
|

Re: [GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

cchacin
Thanks David for the feedback and the recommendations, I'll polish
everything in the current open PR/branch and after having everything
working with JBake I'll split the work in smaller separate PRs.

On Wed, Dec 5, 2018 at 6:37 PM David Blevins <[hidden email]>
wrote:

> Thank you for the PR, Carlos!
>
> Give this a try with the site generator:
>
>  - https://github.com/apache/tomee-site-generator
>
> JBake defines header for Asciidoc slightly differently than it does for
> Markdown.  Check out:
>
>  - https://jbake.org/docs/2.6.3/#metadata_header
>
> Specifically, there's no "~~~~~~" terminator and all JBake properties must
> start with ":jbake-".  Important note that ":index-group:" is fine as that
> is one of our headers.
>
> The site generator will create a clone of TomEE master in
> repos/tomee-8.0/.  You can pull your PR into that using this script:
>
>  - https://gist.github.com/dblevins/6e255634d84914beb051a4b3858ebfb4
>
> And then hammer away till it all looks good.
>
> I probably would recommend doing them in batches as you mention in your
> PR, just because you're scripting this and no one is perfect and each page
> should be reviewed with a human eye before being merged or going live.  I
> think one pig PR is a huge time commitment to review in one shot.
>
> Huge thank you for taking this on!!!!
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
> > On Dec 4, 2018, at 1:02 AM, cchacin <[hidden email]> wrote:
> >
> > Github user cchacin commented on the issue:
> >
> >    https://github.com/apache/tomee/pull/234
> >
> >    I'm happy to split this in several PRs if the changes make sense
> >
> >
> > ---
>
>

--
*Carlos Chacin*
Software Developer Engineering
Reply | Threaded
Open this post in threaded view
|

[GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

otaviojava
In reply to this post by otaviojava
Github user cchacin commented on the issue:

    https://github.com/apache/tomee/pull/234
 
    Closing this in favor of a series of following PRs with separate file sets to make the review process easier.


---
Reply | Threaded
Open this post in threaded view
|

[GitHub] tomee pull request #234: TOMEE-2316 Convert Markdown files to Asciidoc in th...

otaviojava
In reply to this post by otaviojava
Github user cchacin closed the pull request at:

    https://github.com/apache/tomee/pull/234


---
Reply | Threaded
Open this post in threaded view
|

Re: [GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

cchacin
In reply to this post by cchacin

Hi, I separated the work in 13 PRs and they are tested locally using JBake

I tried to find a good balance between number of files vs. number of PRs but if you folks think that I should create yet smaller PRs let me know (I have an script for that process)

There already a few noticeable improvements in this migration:

The ASF license header was shown as follow:


And now is shown in a nicer asciidoc admonition:



The JPA section was not shown in the documentation, and now it's there:


New Links appearing in the respective sections:







On Wed, Dec 5, 2018 at 7:57 PM Carlos Chacín <[hidden email]> wrote:
Thanks David for the feedback and the recommendations, I'll polish everything in the current open PR/branch and after having everything working with JBake I'll split the work in smaller separate PRs.

On Wed, Dec 5, 2018 at 6:37 PM David Blevins <[hidden email]> wrote:
Thank you for the PR, Carlos!

Give this a try with the site generator:

 - https://github.com/apache/tomee-site-generator

JBake defines header for Asciidoc slightly differently than it does for Markdown.  Check out:

 - https://jbake.org/docs/2.6.3/#metadata_header

Specifically, there's no "~~~~~~" terminator and all JBake properties must start with ":jbake-".  Important note that ":index-group:" is fine as that is one of our headers.

The site generator will create a clone of TomEE master in repos/tomee-8.0/.  You can pull your PR into that using this script:

 - https://gist.github.com/dblevins/6e255634d84914beb051a4b3858ebfb4

And then hammer away till it all looks good.

I probably would recommend doing them in batches as you mention in your PR, just because you're scripting this and no one is perfect and each page should be reviewed with a human eye before being merged or going live.  I think one pig PR is a huge time commitment to review in one shot.

Huge thank you for taking this on!!!!


--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Dec 4, 2018, at 1:02 AM, cchacin <[hidden email]> wrote:
>
> Github user cchacin commented on the issue:
>
>    https://github.com/apache/tomee/pull/234
>
>    I'm happy to split this in several PRs if the changes make sense
>
>
> ---



--
Carlos Chacin
Software Developer Engineering


--
Carlos Chacin
Software Developer Engineering
Reply | Threaded
Open this post in threaded view
|

Re: [GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

David Blevins-2
Note the license header should only be visible in the source file as a comment that isn't shown on each page.  We have the licensing terms covered for the published website via the footer, which states:

 - Copyright © 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.

We probably should update the copyright year however :)

--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Dec 5, 2018, at 11:53 PM, Carlos Chacín <[hidden email]> wrote:
>
> Hi, I separated the work in 13 PRs and they are tested locally using JBake
>
> • PR #244
> • PR #245
> • PR #246
> • PR #247
> • PR #248
> • PR #249
> • PR #250
> • PR #251
> • PR #252
> • PR #253
> • PR #254
> • PR #255
> • PR #256
> I tried to find a good balance between number of files vs. number of PRs but if you folks think that I should create yet smaller PRs let me know (I have an script for that process)
>
> There already a few noticeable improvements in this migration:
>
> The ASF license header was shown as follow:
>
> <image.png>
> And now is shown in a nicer asciidoc admonition:
>
> <image.png>
>
> The JPA section was not shown in the documentation, and now it's there:
>
> <image.png>
> New Links appearing in the respective sections:
>
> <image.png>
>
> <image.png>
> <image.png>
> <image.png>
>
> On Wed, Dec 5, 2018 at 7:57 PM Carlos Chacín <[hidden email]> wrote:
> Thanks David for the feedback and the recommendations, I'll polish everything in the current open PR/branch and after having everything working with JBake I'll split the work in smaller separate PRs.
>
> On Wed, Dec 5, 2018 at 6:37 PM David Blevins <[hidden email]> wrote:
> Thank you for the PR, Carlos!
>
> Give this a try with the site generator:
>
>  - https://github.com/apache/tomee-site-generator
>
> JBake defines header for Asciidoc slightly differently than it does for Markdown.  Check out:
>
>  - https://jbake.org/docs/2.6.3/#metadata_header
>
> Specifically, there's no "~~~~~~" terminator and all JBake properties must start with ":jbake-".  Important note that ":index-group:" is fine as that is one of our headers.
>
> The site generator will create a clone of TomEE master in repos/tomee-8.0/.  You can pull your PR into that using this script:
>
>  - https://gist.github.com/dblevins/6e255634d84914beb051a4b3858ebfb4
>
> And then hammer away till it all looks good.
>
> I probably would recommend doing them in batches as you mention in your PR, just because you're scripting this and no one is perfect and each page should be reviewed with a human eye before being merged or going live.  I think one pig PR is a huge time commitment to review in one shot.
>
> Huge thank you for taking this on!!!!
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
> > On Dec 4, 2018, at 1:02 AM, cchacin <[hidden email]> wrote:
> >
> > Github user cchacin commented on the issue:
> >
> >    https://github.com/apache/tomee/pull/234
> >
> >    I'm happy to split this in several PRs if the changes make sense
> >
> >
> > ---
>
>
>
> --
> Carlos Chacin
> Software Developer Engineering
>
>
> --
> Carlos Chacin
> Software Developer Engineering

Reply | Threaded
Open this post in threaded view
|

Re: [GitHub] tomee issue #234: TOMEE-2316 Convert Markdown files to Asciidoc in the docs ...

cchacin
I'll create a ticket to put the headers as a code comment instead, I
noticed that is also appearing in the current markdown docs:

http://tomee.apache.org/tomee-8.0/docs/tomee-webapp.html

On Thu, Dec 6, 2018 at 1:47 PM David Blevins <[hidden email]>
wrote:

> Note the license header should only be visible in the source file as a
> comment that isn't shown on each page.  We have the licensing terms covered
> for the published website via the footer, which states:
>
>  - Copyright © 1999-2016 The Apache Software Foundation, Licensed under
> the Apache License, Version 2.0.
>
> We probably should update the copyright year however :)
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
> > On Dec 5, 2018, at 11:53 PM, Carlos Chacín <[hidden email]> wrote:
> >
> > Hi, I separated the work in 13 PRs and they are tested locally using
> JBake
> >
> >       • PR #244
> >       • PR #245
> >       • PR #246
> >       • PR #247
> >       • PR #248
> >       • PR #249
> >       • PR #250
> >       • PR #251
> >       • PR #252
> >       • PR #253
> >       • PR #254
> >       • PR #255
> >       • PR #256
> > I tried to find a good balance between number of files vs. number of PRs
> but if you folks think that I should create yet smaller PRs let me know (I
> have an script for that process)
> >
> > There already a few noticeable improvements in this migration:
> >
> > The ASF license header was shown as follow:
> >
> > <image.png>
> > And now is shown in a nicer asciidoc admonition:
> >
> > <image.png>
> >
> > The JPA section was not shown in the documentation, and now it's there:
> >
> > <image.png>
> > New Links appearing in the respective sections:
> >
> > <image.png>
> >
> > <image.png>
> > <image.png>
> > <image.png>
> >
> > On Wed, Dec 5, 2018 at 7:57 PM Carlos Chacín <[hidden email]> wrote:
> > Thanks David for the feedback and the recommendations, I'll polish
> everything in the current open PR/branch and after having everything
> working with JBake I'll split the work in smaller separate PRs.
> >
> > On Wed, Dec 5, 2018 at 6:37 PM David Blevins <[hidden email]>
> wrote:
> > Thank you for the PR, Carlos!
> >
> > Give this a try with the site generator:
> >
> >  - https://github.com/apache/tomee-site-generator
> >
> > JBake defines header for Asciidoc slightly differently than it does for
> Markdown.  Check out:
> >
> >  - https://jbake.org/docs/2.6.3/#metadata_header
> >
> > Specifically, there's no "~~~~~~" terminator and all JBake properties
> must start with ":jbake-".  Important note that ":index-group:" is fine as
> that is one of our headers.
> >
> > The site generator will create a clone of TomEE master in
> repos/tomee-8.0/.  You can pull your PR into that using this script:
> >
> >  - https://gist.github.com/dblevins/6e255634d84914beb051a4b3858ebfb4
> >
> > And then hammer away till it all looks good.
> >
> > I probably would recommend doing them in batches as you mention in your
> PR, just because you're scripting this and no one is perfect and each page
> should be reviewed with a human eye before being merged or going live.  I
> think one pig PR is a huge time commitment to review in one shot.
> >
> > Huge thank you for taking this on!!!!
> >
> >
> > --
> > David Blevins
> > http://twitter.com/dblevins
> > http://www.tomitribe.com
> >
> > > On Dec 4, 2018, at 1:02 AM, cchacin <[hidden email]> wrote:
> > >
> > > Github user cchacin commented on the issue:
> > >
> > >    https://github.com/apache/tomee/pull/234
> > >
> > >    I'm happy to split this in several PRs if the changes make sense
> > >
> > >
> > > ---
> >
> >
> >
> > --
> > Carlos Chacin
> > Software Developer Engineering
> >
> >
> > --
> > Carlos Chacin
> > Software Developer Engineering
>
>

--
*Carlos Chacin*
Software Developer Engineering