Xfce Wiki

Sub domains
 

~~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

  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

Update your project

  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.

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.

  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.