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/sphinxcontrib-needs node latexpdf
   :max_content_lines: 4
A node can only be in one page, else it will be cut when generate latexpdf (url)
../_images/62423175.png
sophiali2008
user: sophiali2008
created_at: 2020-03-24T08:30:43Z
updated_at: 2021-05-07T11:53:02Z
closed_at: 2021-05-07T11:52:34Z
service: github-issues
url: Link
type: Issue
status: closed
tags: bug, help wanted, no_fix
Hello,

I used the extension needs 0.5.3 in my project, it is
perfectly fit in html.

[...]

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/sphinxcontrib-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: A node can only be in one page, else it will be cut when generate latexpdf GH_141 ../_images/arrow-right-circle.svg
status: closed
tags: awesome, issue, bug, help wanted, no_fix
style: discreet
layout: clean
author: Me
query: repo:useblocks/sphinxcontrib-needs node latexpdf
max_amount: 1
max_content_lines: 4
id_prefix: GH_
user: sophiali2008
created_at: 2020-03-24T08:30:43Z
updated_at: 2021-05-07T11:53:02Z
closed_at: 2021-05-07T11:52:34Z
service: github-issues
url: https://github.com/useblocks/sphinxcontrib-needs/issues/141
avatar: /home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-needs/checkouts/latest/docs/github_images/62423175.png
Hello,

I used the extension needs 0.5.3 in my project, it is
perfectly fit in html.

[...]

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!

Warning

GitHub counts the performed API requests and may reject new requests, if the rate limit is exceeded. This seems to be 10 requests per minute for search-API for unauthenticated users.

You can higher this limit to 30 requests, if you provide a username and token in the service config.

Sphinx-Needs will support you with the current rate limit status, if a request got rejected.

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/sphinxcontrib-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/sphinxcontrib-needs/155

Example:

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

.. needservice:: github-prs
   :specific: useblocks/sphinxcontrib-needs/161
Fix for role need_outgoing (url)
../_images/998700.png
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
need_outgoing showed "none" in most situations.

Fixes #160

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/sphinxcontrib-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/sphinxcontrib-needs node latexpdf
   :max_content_lines: 4
   :layout: focus_l
   :style: blue_border
Hello,

I used the extension needs 0.5.3 in my project, it is
perfectly fit in html.

[...]

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 sphinxcontrib.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/sphinxcontrib-needs python
   :max_amount: 2
string format fix to support python 3.5 (url)
../_images/998700.png
danwos
user: danwos
created_at: 2021-01-06T06:33:48.000+01:00
service: github-commits
url: Link
type: Commit

string format fix to support python 3.5

Poetry (#216) (url)
../_images/33452915.png
danieleades
user: danieleades
created_at: 2021-04-19T15:38:32.000+01:00
service: github-commits
url: Link
type: Commit

Poetry (#216)

  • add nox + poetry files

* update ci.yml

* drop python 3.5 support from CI matrix

* install poetry

* commit poetry lock file

* add sphinx version to CI matrix

* remove quotes

* add missing dollar sign

* change version specifications to strings

* try to set names for the matrix jobs

* remove deprecated files

* treat poetry.lock as a binary

* add more documentation, deprecate setup file

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* tidy up

* tidy noxfile

* update lock file

* bump dependencies

* prune over-enthusiastic use of the word ‘also’

also change a <ul> to an <ol>

* add py39 to test matrix

* move logic from noxfile to Makefile

* add flake8

* fix outstanding lint errors

* add CI target

* re-add ‘test_doc_github_61’

* add linting for pep8 naming compliance

* add trailing newline to file

* fix lint error

* add makefile targets for building docs

* move ‘contributing’ guide from markdown file to docs/ directory

* add missing newline

* fix flake8 lints

Specific commit

Document commit a4a596 of Sphinx-Needs.

.. needservice:: github-commits
   :specific: useblocks/sphinxcontrib-needs/a4a596
Fix for role need_outgoing (#161) (url)
../_images/998700.png
danwos
user: danwos
created_at: 2020-11-17T09:35:33Z
service: github-commits
url: Link
type: Commit

Fix for role need_outgoing (#161)

need_outgoing showed “none” in most situations.

Fixes #160

Filtering

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

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

ID

Title

Type

Service

User

EXAMPLE_141

A node can only be in one page, else it will be cut when generate latexpdf

issue

github-issues

sophiali2008

GH2_141

A node can only be in one page, else it will be cut when generate latexpdf

issue

github-issues

sophiali2008

GH_141

A node can only be in one page, else it will be cut when generate latexpdf

spec

github-issues

sophiali2008

GH_COM_a4a596

Fix for role need_outgoing (#161)

commit

github-commits

danwos

GH_COM_c34eb1

Poetry (#216)

commit

github-commits

danieleades

GH_COM_dc1480

string format fix to support python 3.5

commit

github-commits

danwos

GH_ISSUE_141

A node can only be in one page, else it will be cut when generate latexpdf

issue

github-issues

sophiali2008

GH_PR_161

Fix for role need_outgoing

pr

github-prs

danwos