10 About this site

This site was build using Bookdown (Xie 2015) from Yihui Xie. Thanks!

10.1 Building the site

Source code for the book is maintained in the docs directory of the EML repository in markdown format. To edit the site, make changes to the markdown files and configuration files in docs, and then run the build_book.R script which builds the bookdown version of the site and places the files in the dist directory. The configuration file _bookdown.yml controls the inclusion and order of the chapters. Generally, there is one markdown file for each chapter, and so it should start with a single level 1 heading which will act as the chapter title in the table of contents.

Note that if you have also made changes to the XSD schema files for EML, then you should also regenerate the schema documentation using Oxygen. This requires a trial or licensed version of Oxygen, and can be run using the shell script bin/build_schema_documentation.sh. Here are example commands for updating the site after you’ve changed the markdown documentation and XSD files.

$ ./bin/build_schema_documentation.sh
$ cd docs
$ R -f 'build_book.R'
$ cd ..

At this point, you have a local copy of the documentation built that you can view in a web browser.

10.2 Deploying the site

Once the changes are committed in the docs directory, it is ready to be deployed on the web by pushing the files to the gh_pages branch. Publishing gh_pages content to the web is currently handled by Netlify which publishes the site to the custom domain https://eml.ecoinformatics.org. To deploy a new version of the site, first edit and commit the site changes to the master branch as described in the previous section, and then deploy the site using the provided deployment shell script which updates the gh_pages branch for you:

$ ./bin/deploy_site.sh

This will remove the current dist directory, build a clean copy of the dist directory from the documentation source files, then copy the built files in the dist directory to the gh_pages branch, which will be picked up and deployed by Netlify shortly thereafter to https://eml.ecoinformatics.org.

References

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. http://yihui.name/knitr/.