GitHub services¶

As GitHub provides different kinds of information (e.g. issues, prs or commits), there is a specialised service for each information type:

• github-issues

• github-prs

• github-commits

They all have common configuration options and are using the same way of querying their data. Therefore the below configuration is valid for all three services.

Each services creates normally multiple need objects for each element found by querying the GitHub API.

Example of an imported github issue:

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :max_content_lines: 4

GH_ISSUE_166		Fails to build PDF when 'req' directive contains nested directives (url)		danieleades
user: danieleades created_at: 2021-01-08T12:51:32Z updated_at: 2021-10-20T04:46:28Z closed_at: None service: github-issues url: Link			type: Issue status: open delete: False jinja_content: False
I'm finding that while I can build HTML output (`make html`) the build fails with an extension error when using the PDF target (`make latexpdf`) [...]
layout: github		service: github-issues		style:

Directive options, which can also used for normal needs, can also be set for needservice directive. Also the content part of needservice is added as extra data to the end of the finally created needs.

Example:

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :id_prefix: GH_
   :max_amount: 1
   :max_content_lines: 4
   :type: spec
   :author: Me
   :tags: github, awesome, issue, open
   :layout: clean
   :style: discreet

   Extra content for each new need

Specification: Fails to build PDF when 'req' directive contains nested directives GH_166

status: open tags: awesome, issue style: discreet layout: clean delete: False jinja_content: False author: Me query: repo:useblocks/sphinx-needs node latexpdf max_amount: 1 max_content_lines: 4 id_prefix: GH_ user: danieleades created_at: 2021-01-08T12:51:32Z updated_at: 2021-10-20T04:46:28Z closed_at: None service: github-issues url: https://github.com/useblocks/sphinx-needs/issues/166 avatar: /home/docs/checkouts/readthedocs.org/user_builds/sphinx-needs/checkouts/rtd_jaav/docs/github_images/33452915.png

I'm finding that while I can build HTML output (`make html`) the build fails with an extension error when using the PDF target (`make latexpdf`) [...] Extra content for each new need

Querying objects¶

There are two options for querying objects for GitHub:

query:

Performs a Github search

specific:

Gets a single, specific element from GitHub

Setting query or specific option is mandatory for services github-issues and github-prs!

query¶

The imported objects are based on a query-string, which must be valid to the Github search syntax for issues and pull requests.

To query for issues only, github-issues adds is:issue to the query string automatically. Related to this, github-prs adds is:pr.

Example:

This loads all open issues, which have the strings needtable and viewports in their data.

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs state:open needtable viewports

specific¶

If only a single, specific object shall be documented, using query will not work, as the GitHub Search API does not support query-options for getting a specific element. Instead use specific and provide the unique reference in the syntax owner/repo/number, for example useblocks/sphinx-needs/155

Example:

This query fetches a specific pull request with the id 161.

.. needservice:: github-prs
   :specific: useblocks/sphinx-needs/161

GH_PR_161		Fix for role need_outgoing (url)		danwos
user: danwos created_at: 2020-11-17T08:05:35Z updated_at: 2021-02-15T07:52:39Z closed_at: 2020-11-17T09:35:34Z service: github-prs url: Link			type: PullRequest status: closed tags: bug delete: False jinja_content: False
need_outgoing showed "none" in most situations. Fixes #160
layout: github		service: github-prs		style:

Common Configuration¶

All GitHub related services have a common set of configuration options and their configuration must be done in needs_services inside the project’s conf.py file.

needs_services must contain a key with the service name, e.g. github-issues

The following key-value configuration parameters are known by all GitHub services:

url:

GitHub service instance url. Default: https://api.github.com/

username:

Username if access to private repositories is needed.

token:

Personal GitHub token for login. Can be created in your User profile page.

download_avatars:

True/False, if avatars shall be downloaded. If False a default avatar is used. Needed mostly for GitHub Enterprise, as authentication for avatars may make some trouble.

download_folder:

Folder path for avatar downloads. Default: github_images.

need_type:

Default need type to use, if no type got specified in directive options

max_amount:

The maximum amount of issues to report

max_content_lines:

Maximum amount of lines from issue/pr/commit content to be reported in need content.

id_prefix:

Prefix string for the final need id.

layout:

Layout to use for need. Default is github. See Layouts for details.

All options can be overwritten by setting them directly in the need service directive:

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs
   :type: test
   :max_amount: 10
   :max_content_lines: 2
   :id_prefix: GITHUB_UB_

Example configuration for conf.py:

needs_services = {
    'github-issues': {
        'url': 'https://api.github.com/',
        'need_type': 'spec',
        'max_amount': 2,
        'max_content_lines': 20,
        'id_prefix': 'GH_ISSUE_'
    }
}

Layout¶

The GitHub services are providing a new layout, called github, which is used by default and is based on the standard complete layout.

You can overwrite its usage by setting layout in the service configuration or by setting it directly in the directive needservice.

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :max_content_lines: 4
   :layout: focus_l
   :style: blue_border

I'm finding that while I can build HTML output (`make html`)
the build fails with an extension error when using the PDF
target (`make latexpdf`)


[...]

Need type¶

The GitHub services create 3 new need types: issue, pr and commit. These types are used by default by the related service, but its usage can be overwritten in the service configuration by setting need_type or in the directive directly by setting type.

The configuration (names, colors, diagram representation) can also be overwritten by configuring your own need type in the configuration. Simply use needs_types for this.

Custom service¶

The preconfigured services github_issues, github_prs and github_commits support the cloud instance of GitHub by default.

If a company internal GitHub Enterprise instance shall be addressed, you should configure an additional service to deal with both (cloud and company instance) and being able to set company specific configuration options.

Please see the this example for a Github Enterprise configuration in your conf.py file:

from sphinx_needs.services.github import GithubService

needs_services = {
    # Cloud GitHub configuration
    'github-issues': {
        'max_content_lines': 20,
        'id_prefix': 'GH_ISSUE_',
    },
    # GitHub Enterprise configuration
    'my-company-issues': {
        'class': GithubService,
        'class_init': {
            'gh_type': 'issue'
        },
        'url': 'https://github.my-company.com/api/v3/',
        'username': 'my_username',
        'token':  'my_github_token',
        'download_avatars': True,
        'download_folder': 'company-avatars',
        'max_content_lines': 20,
        'id_prefix': 'COMPANY_ISSUE_',
    }
}

class needs to reference the service-class object and class_init contains service specific initialisation options. In this case you must tell the generic GitHubService class which kind of information it shall deal with. Allowed are issue, pr and commit.

All other options are normal configuration options for the service, which are also available for the GitHub cloud instance.

Examples¶

Commits¶

Search Search for all commits of Sphinx-Needs, which have Python in their message.

.. needservice:: github-commits
   :query: repo:useblocks/sphinx-needs python
   :max_amount: 2

GH_COM_89e6c2		Bump actions/setup-python from 3 to 4 (#600) (url)		dependabot[bot]
user: dependabot[bot] created_at: 2022-06-13T08:44:42.000+02:00 service: github-commits url: Link			type: Commit delete: False jinja_content: False
Bump actions/setup-python from 3 to 4 (#600) Bumps [actions/setup-python](https://github.com/actions/setup-python) from 3 to 4. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v3…v4) — updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major … Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
layout: github		service: github-commits		style:

GH_COM_968ca9		Bump actions/setup-python from 2 to 3 (url)		dependabot[bot]
user: dependabot[bot] created_at: 2022-03-01T04:29:13.000Z service: github-commits url: Link			type: Commit delete: False jinja_content: False
Bump actions/setup-python from 2 to 3 Bumps [actions/setup-python](https://github.com/actions/setup-python) from 2 to 3. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v2…v3) — updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major … Signed-off-by: dependabot[bot] <support@github.com>
layout: github		service: github-commits		style:

Specific commit

Document commit a4a596 of Sphinx-Needs.

.. needservice:: github-commits
   :specific: useblocks/sphinx-needs/a4a596

GH_COM_a4a596		Fix for role need_outgoing (#161) (url)		danwos
user: danwos created_at: 2020-11-17T09:35:33Z service: github-commits url: Link			type: Commit delete: False jinja_content: False
Fix for role need_outgoing (#161) need_outgoing showed “none” in most situations. Fixes #160
layout: github		service: github-commits		style:

Filtering¶

Show all needs, which have github as part of their service value.

.. needtable::
   :filter: 'github' in service
   :columns: id, title, type, service, user