doc2git – Generate content and push it to git

doc2git is helper tool to generate static content and push it to a remote git repository.

Introduction

Requeriments

doc2git needs Python 3.3 or better

Installation

pip install doc2git

Basic usage

In any folder of your git repository run:

doc2git

Is also possible run with:

d2g

You save 4 characters :-)

Note

Create a file called d2g.ini in the git repository root folder to tell to doc2git what should do, see next section for a better explanation.

Configuration

This is the default doc2git configuration file:

[doc]

# Command to generate the documents.
command = sphinx-build -W -b html docs/source html_output

# Path to the folder with the generated documentation. Is relative to the git
# repository (the folder where your .git folder lives). Files in this folder
# are pushed.
output_folder = html_output

# If you don't want to commit some file in the output_folder, list them here.
# Multiple items are comma separated.
exclude = .buildinfo, .doctrees

# Create some extra files to the commit. This files are created with the
# 'touch' command and are empty.
# Multiple items are comma separated.
extra = .nojekyll


[git]

# Name of the remote repository where you want to push the generated content,
# usually origin.
# If empty, doc2git use the first remote found returned by the command
# "git remote -v". This remote also has to match the service
remote =

# Service name where you want to push your documentation. This name is used to
# look for git remotes.
service = github.com

# Branch name where you want to push. Is created if does't exist.
branch = gh-pages

# Commit message.
message = Autogenerated github-pages

As you can see, default options are for create sphinx documentation and push it to github, but is possible to overwrite any of this options.

doc2git checks for a ini file called d2g.ini in your git root repository folder (the folder with .git folder). If you want to overwrite the default cofiguration, be sure that the file name and its location are correct.

For example, if you want to change the commit message, create this file:

[git]
message = My custom message for every documentation commit.

All the other options have the default value, only message was changed.