Skip to content

Commit 1be9cf5

Browse files
jistrjistr
committed
Remove user docs from the repo
The repo will only have developer docs and adoption tests from now on. The asciidoc user docs would no longer be considered as a source of truth and as such keeping them around would be net negative, resulting in doubling docs maintenance work, and confusion about which docs should be tested by the test suite.
1 parent 49689b0 commit 1be9cf5

186 files changed

Lines changed: 6 additions & 19965 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yaml‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ on: # yamllint disable-line rule:truthy
1010
paths:
1111
- .github/workflows/docs*
1212
- docs_dev/**
13-
- docs_user/**
1413
- Gemfile
1514
- Makefile
1615
jobs:
@@ -31,22 +30,9 @@ jobs:
3130
- name: Install Asciidoc
3231
run: make docs-dependencies
3332

34-
- name: Build upstream user docs
35-
run: make docs-user
36-
- name: Build downstream preview of user docs
37-
run: BUILD=downstream make docs-user
3833
- name: Build dev docs
3934
run: make docs-dev
4035

41-
- name: Test user docs
42-
run: |
43-
INSTALL_YAMLS_REF=$(grep -o install_yamls docs_build/adoption-user/index-downstream.html | wc -l)
44-
if [[ $INSTALL_YAMLS_REF -gt 0 ]]; then
45-
echo user facing docs should NOT mention install_yamls
46-
grep install_yamls docs_build/adoption-user/index-downstream.html
47-
exit 1
48-
fi
49-
5036
- name: Prepare gh-pages branch
5137
run: |
5238
git config user.name github-actions
@@ -103,12 +89,11 @@ jobs:
10389
<body>
10490
10591
<div class="topnav">
106-
<a class="active" href="user/" target="content">User</a>
10792
<a href="dev/" target="content">Contributor</a>
10893
</div>
10994
11095
<div class="asciidoc">
111-
<iframe name="content" width="100%" height="100%" src="user/index.html"></iframe>
96+
<iframe name="content" width="100%" height="100%" src="dev/index.html"></iframe>
11297
</div>
11398
11499
</body>
@@ -117,14 +102,10 @@ jobs:
117102
118103
- name: Commit asciidoc docs
119104
run: |
120-
mv -T docs_build/adoption-user user
121105
mv -T docs_build/adoption-dev dev
122106
123-
mv user/index-upstream.html user/index.html
124-
mv user/index-downstream.html user/downstream.html
125107
mv dev/index-upstream.html dev/index.html
126108
127-
git add user
128109
git add dev
129110
git add index.html
130111
git commit -m "Rendered docs"

‎AGENTS.md‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ There are other adjacent procedures described or linked in the repo that are opt
3434

3535
- There should be parity between the docs and the tests. There may be some legitimate minor differences to account for CI specifics, but in general the intent of the tests is to verify the procedure and the commands from the docs.
3636
- Tests use the `shell` Ansible module liberally, we do not strive for "beautiful Ansible that just uses Python modules". Using `shell` tends to allow verbatim correspondence of tests to the commands/snippets in the docs, which is more important than having beautiful Ansible code.
37-
- Docs must support multiple variants (upstream/downstream/OSPDO). Do not hardcode product names like "Red Hat OpenStack Services on OpenShift". Use the AsciiDoctor attributes defined in `docs_user/adoption-attributes.adoc` (e.g. `{rhos_long}`, `{OpenStackShort}`).
3837

3938
## Important
4039

@@ -43,17 +42,10 @@ There are other adjacent procedures described or linked in the repo that are opt
4342

4443
## Repository map
4544

46-
- `docs_build` - Generated content. Do not read or edit files in this directory as a source of truth. Always use `docs_user` or `docs_dev`.
45+
- `docs_build` - Generated content. Do not read or edit files in this directory as a source of truth. Always use `docs_dev`.
4746
- `docs_build/adoption-dev/index-upstream.html` - Rendered developer documentation.
48-
- `docs_build/adoption-user/index-{upstream,downstream,downstream-ospdo}.html` - Rendered user documentation (the adoption procedure).
4947
- `docs_dev` - Sources for developer documentation.
50-
- `docs_user` - Sources for user documentation (the adoption procedure).
51-
- `main.adoc` is the root.
52-
- `*-attributes.adoc` files distinguish upstream and downstream variants.
53-
- `assemblies` are higher-level building blocks.
54-
- `modules` are lower-level building blocks.
55-
- `docs_user` - Sources for user documentation (the adoption procedure).
56-
- `Makefile` - The main Makefile for docs building and running tests. For docs it calls nested `make` using `docs_dev/Makefile` and `docs_user/Makefile`.
48+
- `Makefile` - The main Makefile for docs building and running tests. For docs it calls nested `make` using `docs_dev/Makefile`.
5749
- `scenarios` - Configuration of CI jobs doing end-to-end testing.
5850
- `tests` - Ansible test suite utilized in the end-to-end tests.
5951
- `vars.sample.yaml,secrets.sample.yaml` - Example files with variables and secrets that are typically customized before running end-to-end tests.
@@ -62,7 +54,7 @@ There are other adjacent procedures described or linked in the repo that are opt
6254

6355
## Building docs
6456

65-
`make docs` is the easiest way to build both user docs in all variants and developer docs.
57+
`make docs` is the easiest way to build developer docs.
6658

6759
More detailed info is in `docs_dev/assemblies/documentation.adoc`.
6860

‎Makefile‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -117,21 +117,7 @@ docs-dependencies: .bundle
117117

118118
bundle config set --local path 'local/bundle'; bundle install
119119

120-
docs: docs-dependencies docs-user-all-variants docs-dev ## Build documentation
121-
122-
docs-user-all-variants:
123-
cd docs_user; BUILD=upstream $(MAKE) html
124-
cd docs_user; BUILD=downstream $(MAKE) html
125-
cd docs_user; BUILD=downstream BUILD_VARIANT=ospdo $(MAKE) html
126-
127-
docs-user:
128-
cd docs_user; $(MAKE) html
129-
130-
docs-user-open:
131-
cd docs_user; $(MAKE) open-html
132-
133-
docs-user-watch:
134-
cd docs_user; $(MAKE) watch-html
120+
docs: docs-dependencies docs-dev ## Build documentation
135121

136122
docs-dev:
137123
cd docs_dev; $(MAKE) html

‎docs_dev/assemblies/documentation.adoc‎

Lines changed: 1 addition & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,22 +9,14 @@ Install docs build requirements:
99
make docs-dependencies
1010
----
1111

12-
To render the user-facing documentation site locally:
13-
14-
[,bash]
15-
----
16-
make docs-user
17-
----
18-
1912
To render the contributor documentation site locally:
2013

2114
[,bash]
2215
----
2316
make docs-dev
2417
----
2518

26-
The built HTML files are in `docs_build/adoption-user` and
27-
`docs_build/adoption-dev` directories respectively.
19+
The built HTML files are in `docs_build/adoption-dev` directory.
2820

2921

3022
There are some additional make targets for convenience. The following
@@ -33,8 +25,6 @@ resulting HTML in your browser so that you don't have to look for it:
3325

3426
[,bash]
3527
----
36-
make docs-user-open
37-
# or
3828
make docs-dev-open
3929
----
4030

@@ -46,22 +36,9 @@ browser page" loop when working on the docs, without having to run
4636

4737
[,bash]
4838
----
49-
make docs-user-watch
50-
# or
5139
make docs-dev-watch
5240
----
5341

54-
=== Preview of downstream documentation
55-
56-
To render a preview of what should serve as the base for downstream
57-
docs (e.g. with downstream container image URLs), prepend
58-
`BUILD=downstream` to your make targets. For example:
59-
60-
[,bash]
61-
----
62-
BUILD=downstream make docs-user
63-
----
64-
6542
== Patterns and tips for contributing to documentation
6643

6744
* Pages concerning individual components/services should make sense in

‎docs_user/.vale.ini‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs_user/.vale/styles/AsciiDocDITA/AdmonitionTitle.yml‎

Lines changed: 0 additions & 70 deletions
This file was deleted.

‎docs_user/.vale/styles/AsciiDocDITA/AttributeReference.yml‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎docs_user/.vale/styles/AsciiDocDITA/AuthorLine.yml‎

Lines changed: 0 additions & 54 deletions
This file was deleted.

0 commit comments

Comments
 (0)