Skip to content

Commit 0a981d8

Browse files
pedro-psbpedro-psb
committed
Improve reference, overviews, add quicklinks
1 parent 7277103 commit 0a981d8

File tree

15 files changed

+545
-35
lines changed

15 files changed

+545
-35
lines changed

‎src/pulp_docs/mkdocs_macros.py

+12-6
Original file line numberDiff line numberDiff line change
@@ -135,14 +135,20 @@ def _place_doc_files(src_dir: Path, docs_dir: Path, repo: Repo):
135135
# Get CHANGELOG
136136
# TODO: remove reading .rst (plugins should provide markdown CHANGELOG)
137137
repo.status.has_changelog = False
138+
changes_dir = Path(docs_dir / "changes")
139+
changes_dir.mkdir(exist_ok=True)
138140
for changelog_name in ("CHANGELOG.md", "CHANGES.md", "CHANGES.rst"):
139141
changelog_path = Path(src_dir / changelog_name)
140142
if changelog_path.exists():
141-
reference_dir = Path(docs_dir / "docs/reference")
142-
reference_dir.mkdir(exist_ok=True)
143-
shutil.copy(changelog_path, reference_dir / "CHANGELOG.md")
143+
shutil.copy(changelog_path, changes_dir / "changelog.md")
144144
repo.status.has_changelog = True
145-
break
145+
return
146+
147+
# Create placeholder, case it was not possible to fetch one
148+
empty_changelog = changes_dir / "changelog.md"
149+
empty_changelog.write_text(
150+
"# Changelog\n\nThe repository does not provide a changelog or there was a problem fetching it."
151+
)
146152

147153

148154
def _generate_rest_api_page(docs_dir: Path, repo_name: str, repo_title: str):
@@ -261,9 +267,9 @@ def get_repos(repo_type="content"):
261267
{
262268
"title": repo.title,
263269
"version": "3.12.1",
264-
"rest_api": f"https://docs.pulpproject.org/{repo.name}/restapi.html",
270+
"rest_api_url": f"https://docs.pulpproject.org/{repo.name}/restapi.html",
265271
"codebase_url": f"https://github.com/{repo.owner}/{repo.name}",
266-
"changelog_url": f"site:pulp-docs/docs/sections/help/changelogs/{repo.name}.md",
272+
"changelog_url": f"site:{repo.name}/changes/changelog/",
267273
}
268274
for repo in repos_list
269275
]

‎src/pulp_docs/navigation.py

+21-7
Original file line numberDiff line numberDiff line change
@@ -118,16 +118,30 @@ def grouped_by_persona(tmpdir: Path, repos: Repos):
118118
]
119119
},
120120
{
121-
"Plugins": f.repo_grouping(
122-
"{repo}/docs/dev/{content}", repo_types=["content"]
123-
)
124-
},
121+
"Plugins": f.repo_grouping( "{repo}/docs/dev/{content}", repo_types=["content"] ) },
125122
{"Extras": f.repo_grouping("{repo}/docs/dev/{content}", repo_types=["other"])},
126123
]
127124
help_section = [
128-
{"Overview": f.section_file("help/index.md")},
129-
{"How to use this documentation": f.section_file("help/bugs-features.md")},
130-
{"Changelog": f.repo_grouping("{repo}/CHANGES.md")},
125+
*f.get_children("pulp-docs/docs/sections/help/community"),
126+
{"Documentation Usage": f.get_children("pulp-docs/docs/sections/help/using-this-doc")},
127+
{
128+
"Changelogs": [
129+
{"Pulpcore": "pulpcore/changes/changelog.md"},
130+
{
131+
"Plugins": sorted(
132+
f.repo_grouping(
133+
"{repo}/changes", repo_types=["content"]
134+
).items()
135+
)
136+
},
137+
{
138+
"Extra": sorted(
139+
f.repo_grouping("{repo}/changes", repo_types=["other"]).items()
140+
)
141+
},
142+
]
143+
},
144+
{"Governance": f.get_children("pulp-docs/docs/sections/help/governance")},
131145
]
132146

133147
# Main Section

‎src/pulp_docs/utils/aggregation.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ def repo_grouping(
6868
6969
Arguments:
7070
template_str: The template with fields to expand. Accepts combination of '{repo}' and '{content}'
71-
repos: The set of repos to use. Accepts list with combination of "core", "content" and "other"
71+
repo_types: The set of repos to use. Accepts list with combination of "core", "content" and "other"
7272
content_types: The set of content-types to use. Accepts combination of "guides", "learn" and "tutorial"
7373
7474
Example:
@@ -94,7 +94,7 @@ def repo_grouping(
9494

9595
# Selected a set of repos
9696
selected_repos = []
97-
selected_content = content_types or ["tutorials", "guides", "learn"]
97+
selected_content = content_types or ["tutorials", "guides", "learn", "reference"]
9898
if not repo_types: # default case
9999
selected_repos = self.repos.all
100100
else:
@@ -108,7 +108,7 @@ def repo_grouping(
108108
)
109109
_repo_content = self.get_children(lookup_path)
110110
if _repo_content:
111-
_nav[repo.title] = _repo_content
111+
_nav[repo.title] = _repo_content if len(_repo_content) > 1 else _repo_content[0]
112112
# Expand content-types
113113
else:
114114
for repo in selected_repos:

‎staging_docs/dev/reference/markdown-cheatsheet.md

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Markdown Cheatsheet
2+
3+
There are basic markdown features recommended for use in Pulp.
4+
5+
### Internal links
6+
7+
=== "Template"
8+
9+
```markdown
10+
[My Link](site:{repo-name}/docs/{persona}/{content-type}/some-page.md).
11+
```
12+
13+
=== "Sample"
14+
15+
```markdown
16+
[My Link](site:pulp-docs/docs/dev/reference/markdown-cheatsheet.md).
17+
```
18+
19+
=== "Sample Rendered"
20+
21+
```markdown
22+
[My Link](http://127.0.0.1:8000/pulp-docs/docs/dev/reference/markdown-cheatsheet/).
23+
```
24+
25+
- This is enabled by [mkdocs-site-urls](https://github.com/octoprint/mkdocs-site-urls) plugin.
26+
- This is preferred over *relative* links because of our complex structure. See tradeoffs [here](https://github.com/pedro-psb/pulp-docs/issues/2)
27+
28+
29+
### Codeblocks
30+
31+
32+
=== "Raw"
33+
34+
````
35+
```
36+
<location "/pulp/api/v3/foo_route">
37+
proxypass /pulp/api http://${pulp-api}/pulp/api
38+
proxypassreverse /pulp/api http://${pulp-api}/pulp/api
39+
requestheader set foo "asdf"
40+
</location>
41+
```
42+
````
43+
44+
---
45+
46+
```
47+
<location "/pulp/api/v3/foo_route">
48+
proxypass /pulp/api http://${pulp-api}/pulp/api
49+
proxypassreverse /pulp/api http://${pulp-api}/pulp/api
50+
requestheader set foo "asdf"
51+
</location>
52+
```
53+
54+
=== "Python Language"
55+
56+
````
57+
```python
58+
serializer = mymodelserializer(data=data)
59+
serializer.is_valid(raise_exception=true)
60+
instance = serializer.create(serializer.validated_data)
61+
```
62+
````
63+
64+
---
65+
66+
```python
67+
serializer = mymodelserializer(data=data)
68+
serializer.is_valid(raise_exception=true)
69+
instance = serializer.create(serializer.validated_data)
70+
```
71+
72+
=== "Python REPL"
73+
74+
````
75+
```python
76+
>>> serializer = mymodelserializer(data=data)
77+
>>> serializer.is_valid(raise_exception=true)
78+
>>> instance = serializer.create(serializer.validated_data)
79+
Some output
80+
```
81+
````
82+
83+
---
84+
85+
```python
86+
>>> serializer = mymodelserializer(data=data)
87+
>>> serializer.is_valid(raise_exception=true)
88+
>>> instance = serializer.create(serializer.validated_data)
89+
Some output
90+
```
91+
92+
=== "With 'Title'"
93+
94+
````
95+
```bash title="script.sh"
96+
pulp file repository update --name myrepo --retained-versions 1
97+
```
98+
````
99+
100+
---
101+
102+
```bash title="script.sh"
103+
pulp file repository update --name myrepo --retained-versions 1
104+
```
105+
106+
### Tabbed content
107+
108+
109+
<div class="grid" markdown>
110+
111+
````
112+
=== "Run"
113+
114+
```bash
115+
cat myfile.txt
116+
```
117+
118+
=== "Output"
119+
120+
```bash
121+
line1
122+
line2
123+
line3
124+
```
125+
````
126+
127+
=== "Run"
128+
129+
```bash
130+
cat myfile.txt
131+
```
132+
133+
=== "Output"
134+
135+
```bash
136+
line1
137+
line2
138+
line3
139+
```
140+
141+
</div>
142+
143+
- [See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage)
144+
- Each tab title must be in quotes
145+
- Each tab block must have 4 spaces of indent
146+
- Put space around `=== "Title"`
147+
148+
### Admonitions
149+
150+
[See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)
151+
152+
Use them wisely.
153+

‎staging_docs/sections/admin/index.md

+49-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,49 @@
1-
# Overview
1+
---
2+
hide:
3+
- toc
4+
---
5+
<div class="hero-header" markdown>
6+
<h1 class="landing-page-h1"></h1>
7+
8+
## This section is for **admins**
9+
10+
Common needs are to *configure, deploy and maintain Pulp instances*.
11+
12+
13+
14+
<div class="grid cards" markdown>
15+
16+
- **Build and deploy**
17+
18+
---
19+
20+
Start developing your service or application by levaraging our powerfull deployment setups.
21+
22+
- **Engage**
23+
24+
---
25+
26+
Get and provide feedback from the peers to help our Project and your Product to grow.
27+
28+
</div>
29+
</div>
30+
31+
---
32+
33+
## Quick Links
34+
35+
36+
{% for repo_type in ("core", "content") %}
37+
Repo | Version | Rest API | Github Page | Changelog
38+
--- | --- | --- | --- | ---
39+
{% for repo in get_repos(repo_type) -%}
40+
{{ repo.title }} | `{{ repo.version }}` | <a href="{{ repo.rest_api_url}}" target="_blank">:link:</a> | [:link:]({{ repo.codebase_url }}) | [:link:]({{ repo.changelog_url }})
41+
{% endfor %}
42+
{% endfor %}
43+
44+
Repo | Version | Code (Github) | Changelog
45+
--- | --- | --- | ---
46+
{% for repo in get_repos("other") -%}
47+
{{ repo.title }} | `{{ repo.version }}` | [:link:]({{ repo.codebase_url }}) | [:link:]({{ repo.changelog_url }})
48+
{% endfor %}
49+

‎staging_docs/sections/dev/index.md

+51-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,51 @@
1-
# Overview
1+
---
2+
hide:
3+
- toc
4+
---
5+
<div class="hero-header" markdown>
6+
<h1 class="landing-page-h1"></h1>
7+
8+
## This section is for Pulp **developers**
9+
10+
Common needs are to *improve docs, fix bugs and add features*.
11+
12+
13+
14+
<div class="grid cards" markdown>
15+
16+
- **Contributing**
17+
18+
---
19+
20+
Learn the basic for contributing to Pulp: opening PRs, code style, releases cycles and versioning.
21+
22+
23+
- **Deep Dive**
24+
25+
---
26+
27+
Dive-in into Pulp code and architecture to help extend, improve and move the project foward.
28+
29+
30+
</div>
31+
</div>
32+
33+
---
34+
35+
## Quick Links
36+
37+
38+
{% for repo_type in ("core", "content") %}
39+
Repo | Version | Rest API | Github Page | Changelog
40+
--- | --- | --- | --- | ---
41+
{% for repo in get_repos(repo_type) -%}
42+
{{ repo.title }} | `{{ repo.version }}` | <a href="{{ repo.rest_api_url}}" target="_blank">:link:</a> | [:link:]({{ repo.codebase_url }}) | [:link:]({{ repo.changelog_url }})
43+
{% endfor %}
44+
{% endfor %}
45+
46+
Repo | Version | Code (Github) | Changelog
47+
--- | --- | --- | ---
48+
{% for repo in get_repos("other") -%}
49+
{{ repo.title }} | `{{ repo.version }}` | [:link:]({{ repo.codebase_url }}) | [:link:]({{ repo.changelog_url }})
50+
{% endfor %}
51+

‎staging_docs/sections/help/community/00_get-involved.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Get involved
2+
3+
A good way to get more help os reaching out to fellow Pulp users and developers.
4+
5+
## Communication Channels
6+
7+
Feel free to ask and answer questions, give feedback about your experience working with any aspect of Pulp.
8+
Introduce yourself, your project, what you’re hoping to achieve with Pulp. We would be delighted to hear from you and understand how Pulp is helping.
9+
10+
- [Community Forum](https://discourse.pulpproject.org/) on Discourse.
11+
- User Support, Development Discussions, Announcements and more
12+
- [Community Chat Space](https://app.element.io/#/room/#pulp-space:matrix.org) on Matrix.
13+
- `pulp`: User Support
14+
- `pulp-dev`: General Development Discussions
15+
- `pulp-meeting`: Open Floor* and Bug Triage (every Tuesday at 10:30 ET)
16+
- `pulp-{plugin}`: Plugin Specific Discussions
17+
18+
!!! Note "*Open Floor"
19+
20+
Open Floor is a time for developer discussion, feedback, and decisions on code/issues/PRs/process relating to pulpcore or plugins. To participate, put a topic on the agenda.
21+
22+
## Reporting
23+
24+
- For reporting a **bug** or requesting a **feature**:
25+
1. First try to search if some similar issue was not already reported.
26+
2. If not, submit an issue to the appropriate repository (pulpcore, pulp_rpm, pulp-oci-images, etc)
27+
- For **security issue**, send an email to [[email protected]](#) with:
28+
- Pulp version
29+
- Vulnerability description
30+
- Reproduction steps.
31+
32+
## Helpful links
33+
34+
- [Youtube channel](https://www.youtube.com/PulpProject): Demos, even recordings and rich discussions!
35+
- [Twitter](https://twitter.com/pulpproj): Release news

‎staging_docs/sections/help/community/01_pulpcon.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# PulpCon
2+
3+
EDIT ME.

0 commit comments

Comments
 (0)