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.

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

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

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 git submodule update --init doc and pull the submodule.

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.

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

For more information about git submodule you can check the Git Book.