Example GitLab CI YAML files and mkdocs configurations for documentation

.gitlab-ci.yml

image: python:3.7.8-slim

default:
  tags:
    - common_runner
    - docker_spot_runner
    - group_runners

variables:
  USER: "{username}"
  DATABASE: "{database}"

before_script:
  - |
    apt-get update -y && \
    apt-get install -y --no-install-recommends \
    make gcc g++ libpq-dev \
    unixodbc-dev unixodbc-bin unixodbc
  - python3 -m pip install --upgrade --no-cache-dir pip setuptools wheel requests
  - python3 -c 'import certifi; print(certifi.where())'
  - |
    python3<<FILE
    import certifi
    import requests
    
    # write any Python code in here
    urls = (
      'http://{baseurl}/{filename1}.cer',
      'http://{baseurl}/{filename2}.cer',
    )
    for url in urls:
        with open(certifi.where(), 'ab') as f:
            f.write(requests.get(url).content)
    FILE
  - python3 -m pip config set global.cert $(python3 -c 'import certifi; print(certifi.where())')
  - python3 -m pip config set global.index https://nexus3.{baseurl}.com/repository/pypi-all/pypi
  - python3 -m pip config set global.index-url https://nexus3.{baseurl}.com/repository/pypi-all/simple
  - python3 -m pip install -r nexus3-requirements.txt

pages:
  script:
  - echo $USER
  - mkdocs build
  artifacts:
    paths:
    - public
  only:
  - master

example.py

"""
Example source code with builtin docstrings that
are parsed by `mkdocstrings` and used in the docs.

This message/description will be included at the top-level
of the generated API documentation.

Here are the links to each of the these documentation doc tools:

- [`mkdocs`](https://www.mkdocs.org/#getting-started)
- [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/)
- [`mkdocstrings`](https://pawamoy.github.io/mkdocstrings/usage/)

"""

# you can document constants
DATE_FORMAT = '%Y-%m-%d'
"""Default date format to use for all `date` and `datetime` objects"""

# functions - type hints are automatically parsed and used in the docs
def func(a: int, b: int, name: Optional[str]) -> None:
    """
    A brief description of what this function does. You can
    write this over multiple lines. You can also include
    admonitions in the following way (just include sufficent space):
    
    !!! info
        A message. Can include `code` and lists
        
        - A
        - B
        - C
        
    You can also include markdown tables directly in any section
    
    | Variable | Type | Description |
    |:--------:|:----:|:-----------:|
    | A        |`str` | Something...|
    | B        |`int` | Something...|
        
    Parameters:
        a: The first value
        b: The second value
        name:
            If `None`, the name is unused. If `str` is provided,
            it represents the name (etc.)
            
    Returns:
        This function does _something_ and returns `None`
        
    Examples:
    
        Here is some example usage
    
        ```python
        import sys
        
        print("Hello World!")
        sys.exit(0)
        ```

    """
    ...
    return None

# same thing with classes
class Example:
    """
    You can provide a description here with the usual
    markdown and other niceties available
    """
    
    # document methods in the same way as free functions above
    def __init__(self, p: dict):
        """
        Constructor details...
        
        !!! info "See Also"
            [`Example.from_json`](#{package}.{filename}.Example.from_json)

        Parameters:
            p: A `dict` of the parsed contents from an `analysis.json` file
        """
        pass
    
    @classmethod
    def from_json(cls, path: str):
        """
        Initializes a new project directly from an `analysis.json` file.
        
        !!! info "See Also"
            [`Example.from_json`](#{package}.{filename}.Example.__init__)

        Parameters:
            path: The path to the JSON file
        """
        import json

        with open(path, 'r') as f:
            p = json.load(f)

        return cls(p)

mkdocs.yml

site_name: Project Documentation
site_url: https://{username}.gitlab.io/{repository}
repo_url: https://gitlab.com/{username}/{repository}
repo_name: {username}/{repository}
edit_uri: 'blob/master/docs'
site_description: 'Project Documentation'
site_author: 'Team Name'
copyright: 'Copyright'
site_dir: public
docs_dir: docs

nav:
  - Home: index.md
  - 'User Guide': user-guide.md
  - 'API Reference':
    - __init__.py: api/__init__.md
    - analysis.py: api/analysis.md
    - cli.py: api/cli.md
    - data.py: api/data.md
  - About:
    - License: license.md
    - Changelog: changelog.md

theme:
  name: material
  include_search_page: false
  palette:
    scheme: default
    primary: black
    accent: teal
  favicon: img/favicon.ico
  icon:
    logo: fontawesome/regular/newspaper
    repo: fontawesome/brands/gitlab

extra_css:
  - css/mkdocstrings.css

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          selection:
            filters:
              - "!^__"        # exclude any __ methods
              - "^__init__$"  # but include __init__
          rendering:
            show_if_no_docstring: true

extra:
  social:
    - icon: fontawesome/brands/gitlab
      link: {url}
    - icon: fontawesome/brands/confluence
      link: {url}
    - icon: fontawesome/brands/jira
      link: {url}

markdown_extensions:
  - toc:
      permalink: true
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.keys
  - pymdownx.highlight:
      use_pygments: true