Skip to content
Snippets Groups Projects
Verified Commit edfdeaf2 authored by Romain Deville's avatar Romain Deville
Browse files

:wrench: Add base template files

Add base templates folder with :

  - Requirements to build the documentation
  - Basic mkdocs.yml file
  - Template and schema for variables
parent eb1a7eb7
No related branches found
No related tags found
No related merge requests found
This diff is collapsed.
# Schema to validate yaml files describing repo information
type: map
mapping:
regex;([a-zA-z0-9_-]+):
type: map
required: true
example: >-
Provide a dictionnary which main key is compose of alphanumerical values
with `-` and `_`.
mapping:
regex;(name|git_slug_with_namespace|desc):
type: str
required: true
example: >-
Key `name`, `git_slug_with_namespace` and `desc` are string and are
required.
regex;(git_name_with_namespace|logo):
type: str
required: false
example: >-
Key `git_name_with_namespace` and `logo` are string and are not
required.
src_path:
type: seq
required: false
example: >-
Key `src_path` is a list of string and is not required.
sequence:
- type: str
maintainers:
type: seq
required: true
example: >-
Key `src_path` is a list of dictionary and is required.
sequence:
- type: map
mapping:
regex;(name|mail):
type: str
required: true
example: >-
Key `name` and `mail` are string and are required.
# Schema to validate subrepo.yml
schema;subrepo_map:
type: map
required: true
example: >-
Provide a dictionary which main key is compose of alphanumerical values
with `-` and `_`.
mapping:
nav_entry:
type: str
required: false
example: >-
Key `nav_entry` is a str corresponding to the entry in the `nav` key.
internal:
type: seq
required: false
example: >-
Key `internal` is a list of dictionary information.
sequence:
- type: map
required: true
example: >-
Dict storing information about the subrepo which will be
cloned/pulled.
mapping:
name:
type: str
required: true
example: >-
Key `name` is a str, the foler where the subrepo should be
cloned/pulled.
git_url:
type: str
required: true
example: >-
Key `git_url` is a str validate again a regexp which hold the SSH or
HTTP URL of the repo to be cloned/pulled.
nav_entry:
type: str
required: true
example: >-
Key `nav_entry` is a str corresponding to the entry in the `nav`
key.
subpath:
type: str
required: false
example: >-
Key `subpath` is a str pointing to the path in the subrepo where
there is a file `mkdocs.yaml` and folder `docs`.
external:
type: seq
required: false
example: >-
Key `internal` is a list of dictionary information.
sequence:
- type: map
required: true
example: >-
Dict storing information about the subrepo which will be
cloned/pulled.
mapping:
name:
type: str
required: true
example: >-
Key `name` is a str, the foler where the subrepo should be
cloned/pulled.
git_url:
type: str
required: true
example: >-
Key `git_url` is a str validate again a regexp which hold the SSH or
HTTP URL of the repo to be cloned/pulled.
nav_entry:
type: str
required: true
example: >-
Key `nav_entry` is a str corresponding to the entry in the `nav`
key.
subpath:
type: str
required: false
example: >-
Key `subpath` is a str pointing to the path in the subrepo where
there is a file `mkdocs.yaml` and folder `docs`.
online_url:
type: str
required: true
example: >-
Key `online_url` is a str pointing to online URL of the subrepo
documentation. Can be a full URL or a path relative to the root
regex;([a-zA-z0-9_-]+):
include: subrepo_map
type: map
required: true
mapping:
subrepo:
include: subrepo_map
# Schema to validate vars.yml
type: map
mapping:
# Mkdocs.yaml Section Schema
# ---------------------------------------------------------------------------
regex;(site_name|site_desc|copyright|repo_name):
type: str
required: false
example: >-
Key `site_name`, `site_desc`, `site_url`, `copyright` or `repo_name` are
string and are optional
regex;(site_url|repo_url|site_base_url):
type: url
required: false
example: >-
Key `site_name`, `site_desc`, `site_url`, `copyright` or `repo_name` are
valid URL and are optional
theme:
type: map
required: false
example: Dictionary key `theme` is optional
mapping:
regex;(name|custom_dir|language|logo|favicon):
type: str
required: false
example: >-
Key `name`, `custom_dir`, `language`, `logo` or `favicon` are string
and are optional
regex;(include_search_page|search_index_only):
type: bool
required: false
example: >-
Key `include_search_page` and `search_index_only` are boolean and
are optional
features:
type: seq
required: false
example: List key `features` is composed of string and is optional
sequence:
- type: str
palette:
type: map
required: false
example: Dictionary key `palette` is optional
mapping:
regex;(scheme|primary|accent):
type: str
required: false
example: >-
Key `scheme`, `primary` or `accent` are string and are optional
font:
type: map
required: false
example: Dictionary key `palette` is optional
mapping:
regex;(text|code):
type: str
required: false
example: >-
Key `text` or `code` are string and are optional
icon:
type: map
required: false
example: Dictionary key `icon` is optional
mapping:
regex;(logo|repo):
type: str
required: false
example: >-
Key `logo` or `repo` are string and are optional
# Git platform section schema
# ---------------------------------------------------------------------------
git_platform:
type: map
required: true
example: Dictionary key `git_platform` is required
mapping:
regex;(logo|icon|name):
type: str
required: true
example: >-
Key `logo`, `icon` and `name are string and are required`
url:
type: url
required: true
example: >-
Key `url` is a URL and is required
\ No newline at end of file
# Repo information
# ===========================================================================
# First key MUST be the "slug" of the repo based on the remote, i.e. if remote
# is git@git.domain.tld:username/repo_name.git, then the key will be
# `repo_name`.
repo_name:
# An explicit name for the repo that will be shown on the documentation
# page.
name: "My Repo Name"
# (OPTIONATL) An extension of the explicit name with the namespace in which
# the repo is. For instance, using above remote, the entry will be
# `Username / Repo Name`.
# This entry is not used in the configuration of mkdocs.
git_name_with_namespace: "Namespace / My Repo Name"
# The complete path of the repo from the git_platform["url"]. For instance,
# using, above remote, the entry will be `username/repo_name.git`
git_slug_with_namespace: "namespace/repo_name"
# If the repo documentation is part of a bigger repo, then provide the
# path of the rendered documentation. If the documentation is not part of
# another repo, leave it empty.
url_slug_with_namespace: "subpath_for_url_renderin/repo_slug"
# (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the
# repo. If not specified, path will automatically be set to
# `assets/img/meta/reop_name_logo.png`
#logo: "assets/img/meta/repo_template_logo.png"
# Description of the repo, will be used to setup the mkdocs description.
desc: >-
Repo description with markdown support
# (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
# source code, you will need to provide the path where your source files
# are relative to the root of the repo.
src_path:
- "src"
# List of informations about the main maintainers that will be automatically
# added to the license file in `docs/about/license.md`
maintainers:
- name: "Firstname Lastname"
mail: "mail@domain.tld"
\ No newline at end of file
# Subrepo Information
# ---------------------------------------------------------------------------
# Dictionnary storing location of subrepo to be included in the main repo
# documentation
# The main key MUST be `subrepo`.
subrepo:
# You can provide multiple nesting level of dictionary defining path to
# the subrepo to include to the main repo documentation such as:
# # Name of the directory
# ```
# dir_name:
# # Corresponding EXISTING entry in the `nav` key of mkdocs.
# nav_entry: "Nav Entry"
# # List of subdirectory from `dir_name` which are repos with
# # mkdocs documentation for which only link to the repo documentation
# # will be provided.
# external:
# # i.e. There is a file `mkdocs.yaml` in
# # `dir_name/subrepo_1/mkdocs.yaml` and
# # `dir_name/subrepo_1/docs/_data/subrepo_1.yaml`
# - name: subrepo_1
# # SSH or HTTP link to the online subrepo_1
# git_url: git@domain.tld:namesapce/subrepo_1
# # List of subdirectory from `dir_name` which are repos with
# # mkdocs documentation which will be included in the documentation.
# external:
# # i.e. There is a file `mkdocs.yaml` in
# # `dir_name/subrepo_2/mkdocs.yaml` and
# # `dir_name/subrepo_2/docs/_data/subrepo_2.yaml`
# - name: subrepo_2
# # SSH or HTTP link to the online subrepo_2
# git_url: git@domain.tld:namesapce/subrepo_2
# # Another sub dir_name which also old subrepos
# subdir_name:
# nav_entry: "Sub Nav Entry"
# [...]
# # Another sub dir_name which also old subrepos
# another_dir_name:
# nav_entry: "Another Nav Entry"
# [...]
# ```
# Below is a short example used for the rendering of
# `docs.romaindeville.fr`
my_dotfiles:
nav_entry: My Dotfiles
internal:
- name: myrepos
nav_entry: MyRepos Template
git_url: git@framagit.org:rdeville.private/my_dotfiles/myrepos.git
my_program:
nav_entry: My Programs
external:
- name: direnv_template
nav_entry: Direnv Template
git_url: git@framagit.org:rdeville.private/my_programs/direnv_template.git
- name: mkdocs_template
nav_entry: Mkdocs Template
git_url: git@framagit.org:rdeville.private/my_programs/mkdocs_template.git
# This example will allow to add the following content to the `nav` key
# ```
# nav:
# [...]
# - My Dotfiles:
# # Monorepo will include following mkdocs.yaml
# - MyRepos Template: !include my_dotfiles/myrepos/mkdocs.yaml
# - My Programs:
# # A link will be provided to the external documentation
# - Direnv Template: /my_program/direnv_template/
# - Mkdocs Template: /my_program/mkdocs_template/
# ```
# Extra Data Information & Customization
# ===========================================================================
# Dictionnary storing variables to be used as "Jinja2" variables within
# markdown files and _data/plugins.py
# Mkdocs.yaml
# ---------------------------------------------------------------------------
# Here you can overwrite main key you could find in mkdocs.yaml
# The name of your site, if not specified, will be the entry `name` of the repo in
# `_data/repo_name.yaml`
#site_name: "Your Site Name"
# The site description of your site, if not specified will be the description
# of the repo in `_data/repo_name.yaml`
#site_desc: "A short description"
# The url of your site, if not specified, then the site_url will be build from
# the key `site_base_url` below and the `url_slug_with_namespace` in
# `_data/repo_name.yaml`. If `site_base_url` is not specified, then value of
# `site_url` will not be overwritten.
#site_url: "https://my_site.tld"
# The name or company which old the copyright. No need to specify any date
# as it will be built based on the first commit of your repo. If not specify,
# then no copyright will be shown on the footer of the documentation.
#copyright: "Firstname Lastname"
# Name of your repo, if not specified, will be the key `mkdocs_repo_name` in
# `_data/repo_name.yaml` If value is EXACTLY "!!git_platform", then the value
# will be `git_platform["name"]` (see below).
#repo_name: "My Repo Name"
# URL to the source code of your repo. If not specified, will be build from
# `git_platform["url"]` (see below) and `repo_name["git_slug_with_namespace"]`
# in `_data/repo_name.yaml`.
#repo_url: "https://mygit.tld/namespace/repo_name
# You can override every entry of the `theme` key in `mkdocs.yaml`, here.
# Usefull to override templated mkdocs.
#
# REMARK, ONLY FOR MATERIAL-MKDOCS THEME
# If `theme["logo"]` is not specified, i.e. path to the logo image, then it
# will be set to the value of the key `repo_name["logo"]` in
# `_data/repo_name.yaml` if specified.
#
# If `theme["favicon"]` is not specified, i.e. path to the favicon image,
# then it will be set to the value of the key `repo_name["logo"]` in
# `_data/repo_name.yaml` if specified.
#
# If `theme["icon"]["repo"]` is not specified, i.e. icon "path" (see
# https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) that
# will be shown on the top rigt corner in front off the repo name, then it
# will be set to the value of the key `git_platform["icon"]` (see below).
#theme:
# logo: "path/to/logo.svg"
# icon:
# repo: fontawesome/brands/gitlab
# favicon: "path/to/favicon.svg"
# Main repo configuration
# ---------------------------------------------------------------------------
# Here you can specify variable about your main repo documentation
# The base url of your site, e.g. if you are using multiple nested
# documentation build with monorepo, you might want to share the same base URL
# for all your repo, then build link from the repo["url_slug_with_namespace"].
#site_url: "https://my_site.tld"
# Git platform
# ---------------------------------------------------------------------------
# In this REQUIRED section you will be able to specify some information for you
# git platform hosting your repo. This section will be used to automatically
# setup configuration for mkdocs such as `repo_url`, theme["icon"]["repo"] etc.
# Main dict entry
git_platform:
# The logo of the git platform you use. Not used in mkdocs configuration but
# can be used in markdown documentation file.
logo: " "
# Icon "path" (see
# https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) that
# will be shown on the top rigt corner in front off the repo name if not
# specified in `theme["icon"]["repo"]`.
icon: "fontawesome/brands/gitlab"
# Name of the platform you use.
name: "Framagit"
# URL of the platform you use, to be able to set `repo_url` for mkdocs
# configuration.
url: "https://framagit.org/"
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment