epythet.tools.published_docs

Elements for a tool to setup docs and check if docs are published, and if not, why.

>>> from epythet.tools.published_docs import published_doc_diagnosis_df
>>> published_doc_diagnosis_df('https://github.com/i2mint/epythet')  
                                 url                      doc_page_url  doc_page_exists  repo_has_docs_folder
0  https://github.com/i2mint/epythet  https://i2mint.github.io/epythet             True                  True
>>> published_doc_diagnosis_df([  
...     'https://github.com/i2mint/epythet', 'https://github.com/otosense/omisc',
... ])
                                 url                      doc_page_url  doc_page_exists  repo_has_docs_folder
0  https://github.com/i2mint/epythet  https://i2mint.github.io/epythet             True                  True
1  https://github.com/otosense/omisc  https://otosense.github.io/omisc            False                 False

epythet.tools.published_docs.branch_exists(repo_stub: str, branch: str, *, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>, verbose=True)[source]

Check if a branch exists in a repo.

Parameters:

repo_stub – A string of the form org/repo.
branch – The branch name to check for.
headers – A function that returns a dictionary of headers

epythet.tools.published_docs.check_token_scopes(token=None, *, verbose=True)[source]: Check the scopes of a GitHub token.

epythet.tools.published_docs.commit_data(repo_stub: str, branch: str, *, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>) → dict[source]: Retrieves data about the latest commit on a branch of a GitHub repository.

epythet.tools.published_docs.configure_github_pages(repo_stub: str, *, target_branch='gh-pages', folder='/', ensure_branch_exists=True, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>, verbose=True)[source]

Configure or update GitHub Pages for a repo.

Example:

>>> configure_github_pages('i2mint/epythet')  

epythet.tools.published_docs.configure_github_pages_for_repo_stubs(repo_stubs: Iterable[str] | str)[source]

Configure Pages for an iterable of repo stubs, or all repos in an organization.

>>> repo_pages_status = dict(
...     configure_github_pages_for_stubs('i2mint')  
... )

epythet.tools.published_docs.default_branch_and_commit_sha(repo_stub: str, *, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>) → dict[source]

Retrieves the default branch and current commit SHA for a given GitHub repository.

Parameters:

repo_stub (str) – The GitHub repository in “owner/repo” format.
headers (dict) – Headers for authentication, e.g., {‘Authorization’: ‘Bearer <token>’}.

Returns:

A dictionary containing ‘default_branch’ and ‘commit_sha’.

Return type:

dict

epythet.tools.published_docs.ensure_branch(repo_stub: str, *, branch: str, commit_sha: str | None = None, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>, verbose=True) → dict[source]

Ensures a branch exists. Does nothing if it already does, and creates it if not.

Parameters:

repo_stub (str) – Owner and name of the GitHub repository, e.g., ‘owner/repo’.
branch (str) – Name of the branch to be created if it doesn’t exist
commit_sha (str) – Commit SHA to base the new branch on. By default, it’s the SHA of the most recent commit of the default branch.
headers (dict) – Headers for authentication, e.g., {‘Authorization’: ‘Bearer <token>’}.

Returns:

Response from GitHub API as a dictionary.

Return type:

dict

epythet.tools.published_docs.github_org_and_repo(github_url)[source]

>>> github_org_and_repo('https://github.com/i2mint/i2')
{'org': 'i2mint', 'repo': 'i2'}

epythet.tools.published_docs.published_doc_diagnosis_df(urls: str | Iterable[str] | Iterable[Iterable] = 'https://raw.githubusercontent.com/otosense/content/main/tables/projects.csv', url_column='url')[source]

The published_doc_diagnosis_df gets you a pandas dataframe (requires pandas to be installed!) that will tell you if given github org/repo url(s) have published documentation and if a docs folder even exists (in master branch).

Parameters:

urls – A list of urls, a table containing urls, or a single url pointing to a csv where this table can be downloaded from.
url_column – When urls is a table, what column name contains the urls.

Returns:

A dataframe with the diagnosis

epythet.tools.published_docs.repo_data(repo_stub: str, *, headers: dict | ~typing.Callable[[], dict] = <function dflt_headers>) → dict[source]: Retrieves data about a GitHub repository.

epythet.tools.published_docs.repo_url_to_docs_url(repo_url)[source]

>>> repo_url_to_docs_url('https://github.com/i2mint/i2')
'https://i2mint.github.io/i2'

epythet.tools.published_docs.repo_url_to_repo_docs_url(repo_url)[source]

>>> repo_url_to_repo_docs_url('https://github.com/i2mint/i2')
'https://github.com/i2mint/i2/tree/master/docs'