README
======

Documentation of an Ansible project


Customize the templates in dir source
-------------------------------------

* Replace __AUTHOR_FULL_NAME__ by the full name of the author
  Example:
  find source -name '*.rst' -o -name '*.py' | xargs -i 's/__AUTHOR_FULL_NAME__/Vladimir Botka/g'

* Replace __COPYRIGHT_HOLDER__ by the copyright holder
  Example:
  find source -name '*.rst' -o -name '*.py' | xargs sed -i 's/__COPYRIGHT_HOLDER__/Vladimir Botka/g'

* Replace __GITHUB_USERNAME__ by the GitHub username
  Example:
  find source -name '*.rst' -o -name '*.py' | xargs sed -i 's/__GITHUB_USERNAME__/vbotka/g'

* Replace __GALAXY_PROJECT__ by the name of the Ansible Galaxy project
  Example:
  https://galaxy.ansible.com/__GITHUB_USERNAME__/__GALAXY_PROJECT__
  find source -name '*.rst' -o -name '*.py' | xargs sed -i 's/__GALAXY_PROJECT__/freebsd_custom_image/g'

* Replace __PROJECT__ by the name of the GitHub project
  Example:
  https://github.com/__GITHUB_USERNAME__/ansible-__PROJECT__
  find source -name '*.rst' -o -name '*.py' | xargs sed -i 's/__PROJECT__/freebsd-custom-image/g'

* Update version

  shell> grep "version =" source/conf.py 
  version = '0.1'


Customize the templates in dir annotation
-----------------------------------------

* Replace __GITHUB_USERNAME__ by the GitHub username
  Example:
  find annotation -name '*.rst.j2' | xargs sed -i 's/__GITHUB_USERNAME__/vbotka/g'

* Replace __PROJECT__ by the name of the GitHub project
  Example:
  https://github.com/__GITHUB_USERNAME__/ansible-__PROJECT__
  find annotation -name '*.rst.j2' | xargs sed -i 's/__PROJECT__/freebsd-custom-image/g'


Create annotated source code
----------------------------

* See annotation/README and create the required files

* Create lists of files and vars
  shell> cd annotation; ansible-playbook pb-annotations.yml

* Create source/annotation-*.rst
  shell> ansible-playbook playbook.yml


Build documentation
-------------------

* Create html documents
  shell> make html

* Create LaTex and PDF documents
  shell> make latexpdf

* Create epub documents
  shell> make epub

* See the documents
  shell> browser build/html/index.html

# EOF
