Actions

docs.typo3.org Infrastructure

This document describes key components of the docs.typo3.org infrastructure.

Git Repository References

Debian Packages

  • fdupes # used by cron_rebuild.sh to hard-link identical files in /home/mbless/public_html/
  • texlive-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended make

Directories on docs.typo3.org

Various scripts

  • /home/mbless/scripts/ -> [git-docst3oResources]/userroot/scripts/
  • /home/mbless/HTDOCS/
    • github.com/
      • xperseguers/
        • TYPO3.docs.ter-automation/ -> [git-TERautomation]
        • RENDER-DOC/
          • force-render.sh :: helper script to manually enqueue a given extension+version's manual
          • bin/
            • t3xutils.phar
          • queue/ :: unpacked extensions (full) waiting to be rendered, populated by TerTask.php, emptied by RenderTask.php
          • render/ :: working directory, processed by RenderTask.php, see "directory for build" below

Rendered Documentation

  • /home/mbless/public_html/
    • css/ -> [git-docst3oResources]/webroot/css/
    • fonts/ -> [git-docst3oResources]/webroot/fonts/
    • i/ -> [git-docst3oResources]/webroot/i/
    • images/ -> [git-docst3oResources]/webroot/images/
    • js/ -> [git-docst3oResources]/webroot/js/
    • php/ -> [git-docst3oResources]/webroot/php/
    • services/ -> [git-docst3oResources]/webroot/services/
    • t3extras/ -> [git-docst3oResources]/webroot/t3extras/
    • favicon.ico -> [git-docst3oResources]/webroot/favicon.ico
    • --------------------------------------------------------
    • typo3cms/extensions/ :: fully managed by [git-TERautomation]
      • manuals.json :: used by TER on typo3.org to link to documentation
      • <extension-key>/

Cron Jobs

  • As user marble ($ crontab -l):
10,40 * * * * /usr/bin/php /home/mbless/HTDOCS/github.com/xperseguers/TYPO3.docs.ter-automation/Classes/Task/TerTask.php >/dev/null 2>&1
*/30 * * * * /usr/bin/php /home/mbless/HTDOCS/github.com/xperseguers/TYPO3.docs.ter-automation/Classes/Task/RenderTask.php >/dev/null 2>&1
*/5 * * * * /home/mbless/HTDOCS/git.typo3.org/Documentation/cron_rebuild.sh

Scripts

cron_rebuild.sh

  • BEWARE: we have many "cron_rebuild.sh" scripts on this server, most of them are used to loop various Sphinx projects to rebulid them
  • The others are ALL symbolic links to /home/mbless/scripts/bin/cron_rebuild.sh

A typical project to be rendered consists of 2 distinct directories:

  • A directory containing the Sphinx documentation (reStructuredText), often under /path/to/<extension>/Documentation/
  • A directory for the build:
    • cron_rebuild.conf
    • cron_rebuild.sh -> /home/mbless/scripts/bin/cron_rebuild.sh
    • Makefile -> /home/mbless/scripts/config/Makefile
    • REBUILD_REQUESTED :: "trigger" used by cron_rebuild.sh to actually run, automatically removed when invoking cron_rebuild.sh
    • various files (warnings.txt, ...) generated by sphinx-doc when invoking cron_rebuild.sh

cron_rebuild.conf

This is a configuration file, format is bash, included (=sourced) by cron_rebuild.sh to know what to do (name of the project, where it is located, where to publish to, ...).
In case of [git-TERautomation], it is dynamically generated for the currently-processed extension.

PROJECT=sphinx
VERSION=1.3.1

# Where to publish documentation
BUILDDIR=/home/mbless/public_html/typo3cms/extensions/sphinx/$VERSION

# If GITURL is empty then GITDIR is expected to be "ready" to be processed
GITURL=git://git.typo3.org/TYPO3CMS/Extensions/sphinx.git
GITDIR=/home/mbless/HTDOCS/git.typo3.org/TYPO3v4/Extensions/sphinx.git
GITBRANCH=$VERSION

# Path to the documentation within the Git repository
T3DOCDIR=$GITDIR/Documentation

# Packaging information
PACKAGE_ZIP=1
PACKAGE_KEY=typo3cms.extensions.sphinx
PACKAGE_LANGUAGE=default

Other Information

Topics for the Code Sprint

  • Security (REMOVE directory listings once for all) [suggested by Georg]

Updated by Xavier Perseguers almost 8 years ago ยท 1 revisions