Skip to content

Commit

Permalink
add 'pulp-core serve' and repolist.yml parsing
Browse files Browse the repository at this point in the history
- pulp-core serve: calls mkdocs serve with the right mkdocs.yml (from
  pulp-docs packaged data)
- repolist.yml: the file describing the repositories to be included
  in the docs and information to fetch them (local/remote URI).
  • Loading branch information
pedro-psb committed Dec 26, 2023
1 parent fec2e23 commit 0b557f9
Show file tree
Hide file tree
Showing 5 changed files with 164 additions and 34 deletions.
36 changes: 35 additions & 1 deletion src/pulp_docs/main.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
import subprocess
import sys
from pathlib import Path

import click
from importlib_resources import files

from pulp_docs.fetch_repos import LocalRepo, download_repos

TMP_DIR = Path("tmp")
Expand All @@ -11,7 +15,37 @@ def get_abspath(name: str) -> Path:
return Path(WORKDIR / name).absolute()


def main():
class Config:
def __init__(self):
self.verbose = False
self.workdir = Path()


pass_config = click.make_pass_decorator(Config, ensure=True)


@click.group()
@pass_config
def main(config: Config):
"""
This is pulp-docs, a cli tool to help run and build multirepo documenation within Pulp project.
"""


@main.command()
@pass_config
def serve(config: Config):
"""Run mkdocs server"""
mkdocs_file = files("pulp_docs").joinpath("mkdocs.yml")
print(mkdocs_file)
cmd = ("mkdocs", "serve", "-f", mkdocs_file)
subprocess.run(cmd)


@main.command()
@pass_config
def pull(config: Config):
"""Pull repositories source from remote into WORKDIR"""
repolist = [
LocalRepo("Pulp Rpm", get_abspath("new_repo1")),
LocalRepo("Pulp Rpm", get_abspath("new_repo2")),
Expand Down
17 changes: 4 additions & 13 deletions src/pulp_docs/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,11 @@ site_name: Pulp Project
repo_url: https://github.com/pulp/pulpcore
repo_name: pulp/pulpcore

docs_dir: .
docs_dir: docs
theme:
name: material
# custom_dir: docs/overrides
logo: pulp-docs/assets/logo.png
features:
# - navigation.footer # customize this color later
- navigation.tabs
- navigation.sections
- navigation.path
Expand Down Expand Up @@ -47,11 +45,6 @@ plugins:
options:
show_source: false
docstring_section_style: table # table, list, spacy
# paths:
# - tmp_dir/repo_sources/core
# - tmp_dir/repo_sources/new_repo1
# - tmp_dir/repo_sources/new_repo2
# - tmp_dir/repo_sources/new_repo3

extra:
social:
Expand All @@ -74,17 +67,15 @@ markdown_extensions:
- md_in_html
- toc:
permalink: true

# Python Markdown Extensions
- pymdownx.arithmatex:
generic: true
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.details
# - pymdownx.emoji:
# emoji_index: !!python/name:material.extensions.emoji.twemoji
# emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
Expand Down
91 changes: 71 additions & 20 deletions src/pulp_docs/mkdocs_macros.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,36 +3,78 @@
import shutil
import tempfile
import typing as t
from dataclasses import dataclass
from dataclasses import dataclass, field
from pathlib import Path

import yaml
from importlib_resources import as_file, files

WORKDIR = Path("tests/fixtures").absolute()
RESTAPI_TEMPLATE = "https://docs.pulpproject.org/{}/restapi.html"
PERSONAS = ("dev", "sys-admin", "content-manager")


@dataclass
class Repo:
title: str
name: str
rest_api_url: str

@property
def url(self):
return WORKDIR / self.name

@property
def rest_api_url(self):
return RESTAPI_TEMPLATE.format(self.name)


RESTAPI_TEMPLATE = "https://docs.pulpproject.org/{}/restapi.html"
PERSONAS = ("dev", "sys-admin", "content-manager")
COMMON_REPO = [Repo("Pulp Core", "core", RESTAPI_TEMPLATE.format("pulpcore"))]
CONTENT_REPOS = [
Repo("Rpm Packages", "new_repo1", RESTAPI_TEMPLATE.format("pulp_rpm")),
Repo("Debian Packages", "new_repo2", RESTAPI_TEMPLATE.format("pulp_deb")),
Repo("Maven", "new_repo3", RESTAPI_TEMPLATE.format("pulp_maven")),
@dataclass
class Repos:
core: Repo
content: t.List[Repo] = field(default_factory=list)
other: t.List[Repo] = field(default_factory=list)

@property
def all(self):
return [self.core] + self.content + self.other

@classmethod
def from_yaml(cls, path: str):
"""
Load repositories listing from yaml file
Example:
```yaml
repos:
core:
name:
title:
content:
- name: pulp_rpm
title: Rpm Package
- name: pulp_maven
title: Maven
```
"""
file = Path(path)
if not file.exists():
raise ValueError("File does not exist:", file)

with open(file, "r") as f:
data = yaml.load(f, Loader=yaml.SafeLoader)
repos = data["repos"]
core_repo = Repo(**repos["core"][0])
content_repos = [Repo(**repo) for repo in repos["content"]]
other_repos = [Repo(**repo) for repo in repos["other"]]
return Repos(core=core_repo, content=content_repos, other=other_repos)


DEFAULT_CORE = Repo("Pulp Core", "core")
DEFAULT_CONTENT_REPOS = [
Repo("Rpm Packages", "new_repo1"),
Repo("Debian Packages", "new_repo2"),
Repo("Maven", "new_repo3"),
]
OTHER_REPOS = [] # type: ignore
ALL_REPOS = COMMON_REPO + CONTENT_REPOS + OTHER_REPOS


def create_clean_tmpdir(project_dir: Path):
Expand All @@ -56,7 +98,7 @@ def download_repo(origin: Path, dest: Path):
raise NotImplementedError("No support for remote download yet.")


def get_navigation(tmpdir: Path):
def get_navigation(tmpdir: Path, repos: Repos):
"""The dynamic generated 'nav' section of mkdocs.yml"""

# {repo}/docs/{persona}/{content-type}/*md
Expand All @@ -69,15 +111,15 @@ def get_children(path: t.Union[str, Path]):

def expand_repos(template_str: str):
_nav = {}
for repo in CONTENT_REPOS:
for repo in repos.content:
lookup_path = tmpdir / template_str.format(repo=repo.name)
_repo_content = get_children(lookup_path)
_nav[repo.title] = _repo_content
return _nav

def expand_reference(template_str: str):
_nav = {}
for repo in ALL_REPOS:
for repo in repos.all:
lookup_path = tmpdir / template_str.format(repo=repo.name)
_repo_content = get_children(lookup_path)
reference_section = [
Expand Down Expand Up @@ -135,7 +177,7 @@ def expand_reference(template_str: str):
return navigation


def prepare_repositories(TMPDIR: Path):
def prepare_repositories(TMPDIR: Path, repos: Repos):
"""
Download repositories into tmpdir and organize them in a convenient way
to mkdocs and its plugins.
Expand All @@ -153,7 +195,7 @@ def prepare_repositories(TMPDIR: Path):
Returns: (Path(repo_docs), Path(repo_sources))
Example:
The final structure will be something like:
The final structure will be something like:
```
tmpdir/
Expand All @@ -172,9 +214,11 @@ def prepare_repositories(TMPDIR: Path):
```
"""

# Download/copy source code to tmpdir
repo_sources_dir = TMPDIR / "repo_sources"
repo_docs_dir = TMPDIR / "repo_docs"
for repo in ALL_REPOS:
for repo in repos.all:
# 1. Download repo (copy locally or fetch from GH)
this_src_dir = repo_sources_dir / repo.name
this_doc_dir = repo_docs_dir / repo.name
Expand Down Expand Up @@ -205,14 +249,21 @@ def prepare_repositories(TMPDIR: Path):

def define_env(env):
"""The mkdocs-marcros 'on_configuration' hook. Used to setup the project."""
# Load repository listing
pulpdocs_repos_list = os.environ.get("PULPDOCS_REPO_LIST", None)
if pulpdocs_repos_list:
repos = Repos.from_yaml(Path(pulpdocs_repos_list))
else:
repos = Repos(core=DEFAULT_CORE, content=DEFAULT_CONTENT_REPOS)

# Create tmp_dir with desired repos
TMPDIR = create_clean_tmpdir(env.project_dir)
docs_dir, source_dir = prepare_repositories(TMPDIR)
docs_dir, source_dir = prepare_repositories(TMPDIR, repos)

# Configure mkdocstrings
code_sources = [str(source_dir / repo.name) for repo in ALL_REPOS]
code_sources = [str(source_dir / repo.name) for repo in repos.all]
env.conf["plugins"]["mkdocstrings"].config["handlers"]["python"]["paths"] = code_sources

# Configure mkdocs navigation
env.conf["docs_dir"] = docs_dir
env.conf["nav"] = get_navigation(docs_dir)
env.conf["nav"] = get_navigation(docs_dir, repos)
16 changes: 16 additions & 0 deletions src/pulp_docs/repolist.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
meta:
rest_api_template: https://docs.pulpproject.org/{}/restapi.html
workdir:

repos:
core:
- name: pulpcore
title: Common
content:
- name: pulp_rpm
title: Rpm Package!!!
- name: pulp_deb
title: Debian Package !!!
- name: pulp_maven
title: Maven
other: []
38 changes: 38 additions & 0 deletions tests/fixtures/core/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,41 @@ hide:
# Welcome to the Pulp Project!

This is a landing page.


<div class="grid cards" markdown>

- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

---

Install [`mkdocs-material`](#) with [`pip`](#) and get up
and running in minutes

[:octicons-arrow-right-24: Getting started](#)

- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

---

Focus on your content and generate a responsive and searchable static site

[:octicons-arrow-right-24: Reference](#)

- :material-format-font:{ .lg .middle } __Made to measure__

---

Change the colors, fonts, language, icons, logo and more with a few lines

[:octicons-arrow-right-24: Customization](#)

- :material-scale-balance:{ .lg .middle } __Open Source, MIT__

---

Material for MkDocs is licensed under MIT and available on [GitHub]

[:octicons-arrow-right-24: License](#)

</div>

0 comments on commit 0b557f9

Please sign in to comment.