search

ctargett / refguide-asciidoc-poc

Proof of concept of Solr Ref Guide converted to asciidoc format & using Asciidoctor for publishing
2 stars 4 forks source link

Version # needs parameterized in build process #25

Closed hossman closed 7 years ago

hossman commented 7 years ago

We need to ensure that anywhere in the ref guide that refers to the version# gets it's info from a variable defined at build time via an ant property.

In some cases this should be easy using asciidoctor run time attributes, which IIUC can be used in pages as if variables, but other places like layout or theme based yaml/json config files may be trickier.

hossman commented 7 years ago

Based on some experimentation today, it seems like there's basically 3 diff things we need to worry about here, to solve both this issue and issue #26 ...

  1. we need to pass the Solr version / javadocs URLs as "attributes" to the asciidoctor ant task when building the PDF so that we can use attribute substitution in the body of adoc files
    • this is fairly easy using the <attribute/> element for the <asciidoctor> ant task
  2. we need to ensure asciidoctor has access to the same version / javadocs URL attributes when it gets invoked by jekyll so it can do the same substitution
    • when jekyll involves asciidoctor, the asciidoctor section of _config.yml defines which attributes get used
    • jekyll doesn't allow command line args to override any config options, but it does allow multiple config files to be specified: https://github.com/jekyll/jekyll/issues/114
    • we can use stuff like ant's ExpandProperties file filter to convert some _adoc_config.yml.template file committed into git, into a _adoc_config.yml file we pass to jekyll with any necessary attribute value variables expanded to some corresponding property: https://ant.apache.org/manual/Types/filterchain.html#expandproperties
  3. we need to ensure the liquid templates have access to some/all of the same attributes so that things like the header/nav/footer have access to them (notably: the solr version#)
    • the easiest way to do this seems to be to generate a _data/ant_properties.yml file containing the properties we need liquid to have access to, and then the templates can access them just like they access the sidebar data via {{ site.data.ant_properties.whatever }}

I'll dig into this more tomorow...

ctargett commented 7 years ago

It's not clear if you know this already, but the liquid templates can pull from _config.yml with syntax like {{site.<param>}} in the templates. The param can be whatever name you want it to be. It feels to me that 3 on your list could be satisfied with that, but I may by missing nuances.

To automate this, is it possible to just have something in Ant or in a script that's run that finds out the version from wherever it's stored in the Solr tree for the dist and package builds and updates _config.yml and build.xml for docs?

hossman commented 7 years ago

It's not clear if you know this already, but the liquid templates can pull from _config.yml ...

I did not realize that -- that simplifies things greatly (i knew about _data/foo.yml being mapped to site.data.foo... but didn't realize you could just get stuff straight from _config.yml)

To automate this, is it possible to just have something in Ant or in a script that's run that finds out the version from wherever it's stored in the Solr tree for the dist and package builds and updates _config.yml ...

yup, yup ... that's basically what i've got locally - a _data/adoc-attributes.yml.template file that ant does property value substituion on to create _data/adoc-attributes.yml with things like solr-docs-version and solr-javadocs properties filled in.

I'll simplify that to just work with a _config.yml.template file instead