GitExtensionsDoc overview - psjw12/gitextensions GitHub Wiki

The documentation for Git Extensions is held in a separate repository from the code repository. The documentation consists of a number of text files written in ReStructuredText (.rst) format, along with image files in Portable Network Graphics (.png) format. The ReStructuredText files are processed using the Sphinx Python Documentation Generator.

The documentation can be generated locally, using scripts supplied as part of the repository. Note that certain pre-requisites are required for this, including Python 2.x and Sphinx. Sphinx supports various output formats including PDF, HTML (separate and one single HTML file) and Microsoft Help format. The documentation can also be generated automatically at the Read the Docs website, ensuring that the online documentation is always up to date.

The documentation repository consists of two permanent branches: master and latest as well as release/ branches. When any changes is updated to these branches, the online documentation at Read the Docs is automatically generated. The branches built on Read the Docs are configured (an administrator for the GitExtensions project can configure the active branches).

This branch reflects the state of the documentation that incorporates all changes in the master branch. Changes to the application source should be updated in this branch too.

This branch reflects the state of the documentation for the latest release of Git Extensions only. The latest release of Git Extensions is that which is available at the official SourceForge link.

These branches are created when releases are done for the application, as the release/ branches for the application.

The Read the Docs website allows for the generation of Sphinx documentation written in ReStructuredText format. A Service Hook has been enabled for the GitExtensionsDoc repository such that when commits are made to the repository, the Read the Docs website is notified and, if the commit is to the 'latest' branch, the documentation is automatically regenerated.

This means the online documentation for the currently released version of Git Extensions is always up to date. The latest documentation in HTML format can be found here.

Read the Docs also generates the documentation in various other formats automatically. These can be downloaded from here. Note that some of these document formats may or may not generate correctly - the content will be there but the formatting of the document may not be correct.

The GitExtensionsDoc repository has the following directory structure.

This is the root directory. Files in this directory include the Windows .cmd files that, when run, will generate various versions of the Git Extensions manual e.g. HTML, Windows Help, PDF, etc.

This directory contains the .rst files. These are the ReStructuredText files that are processed by Sphinx and formatted into the Git Extensions manual.

This directory contains images that are used in the Git Extensions manual e.g. screen prints. Icons are copied from the main repo.

All other sub-directories under images contain images used in various chapters of the manual.

This directory contains the 'theme' that is used when the manual is generated as HTML (either via the .cmd files or on the Read the Docs site).

• to generate documentation locally, Python 2.x i.e. latest 2.x version, is needed, as well as Sphinx. Once Python is installed, the Python Package Manager can be used to install Sphinx and any required dependencies by opening a Command Prompt window and entering at the command prompt:

      pypm install sphinx
  

• to create files that Sphinx can process, refer to the Sphinx documentation for the syntax of .rst files.

• see this online ReStructuredText editor that, via a split screen, allows you to enter ReStructuredText markup and immediately see the results.

In the future, it is anticipated that

• the documentation supplied with a release of Git Extensions will consist of a single HTML file (instead of the current PDF documentation)