~~NOTRANS~~

====== Set up documentation ======

You can follow instructions bellow either to migrate existing documentation from your project, or to create a new documentation. In both cases you need to create a branch for your documentation inside the //xfce4-docs// repository. After that you need to update your project with a git submodule.

===== Xfce4-docs branch =====

  - Clone the repository with write access.
    * ''<nowiki>git clone ssh://<USERNAME>@git.xfce.org/git/xfce/xfce4-docs</nowiki>''
    * ''<nowiki>cd xfce4-docs</nowiki>''
  - Create a branch for your project.
    * ''<nowiki>git checkout --orphan <PROJECT>-master</nowiki>''
  - Copy your documentation inside this new branch.
    * ''<nowiki>cp -r /path/your/project/doc/* ./</nowiki>''
  - Push the new branch.
    * ''<nowiki>git add *</nowiki>''
    * ''<nowiki>git commit -m"Initial <PROJECT> documentation"</nowiki>''
    * ''<nowiki>git push --all</nowiki>''

===== Update your project =====

  - Remove entirely the documentation from your project (e.g. ''rm -rf doc'').
  - Add a submodule from the xfce4-docs read-only repository.
    * ''<nowiki>git submodule add -b <PROJECT>-master git://git.xfce.org/xfce/xfce4-docs doc</nowiki>''
  - Update the ''autogen.sh'' script to use a recent version of xdt-autogen.
    * Snippet: \\ ''XDT_AUTOGEN_REQUIRED_VERSION=<nowiki>"4.7.3"</nowiki> \ \\ XDT_AUTOGEN_CHECK_DOCS=<nowiki>"doc"</nowiki> \ \\ exec xdt-autogen $@''
  - Push the changes.
    * ''<nowiki>git add autogen.sh</nowiki>''
    * ''<nowiki>git commit -m"Include documentation from xfce4-docs"</nowiki>''
    * ''<nowiki>git push</nowiki>''

By now when a user clones the repository, the content of the submodule will automatically be initialized by running the ''autogen.sh'' script. A check within ''xdt-autogen'' will make sure to run the command ''<nowiki>git submodule update --init doc</nowiki>'' and pull the submodule.

===== Keep documentation in sync =====

By including a git submodule inside a project, it is pointing to a specific reference, and you need to keep this reference up to date to point to the latest documentation. You should remember doing this at least before a new release.

  - Get inside your project and make sure the submodule is initialized.
    * ''cd <PROJECT>''
    * ''<nowiki>git submodule update --init</nowiki>''
  - Get inside the submodule and pull the latest revision.
    * ''cd doc''
    * ''git pull''
  - You can check that the reference changed now.
    * ''cd ..''
    * ''git status''
    * ''git diff''
  - Commit the new reference.
    * ''git add doc''
    * ''<nowiki>git commit -m"Update documentation reference"</nowiki>''
    * ''git push''

For more information about git submodule you can check the [[http://book.git-scm.com/5_submodules.html|Git Book]].