Skip to content

Commit 150f8ec

Browse files
tomschrtomschr
committed
Fix #238: Add user portal schema doc
Describe the portal schema from the perspective of a user trying to add or change the config.
1 parent 5e15069 commit 150f8ec

11 files changed

Lines changed: 766 additions & 3 deletions

‎docs/source/user/config/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
Viewing and Validating Configuration
2-
------------------------------------
2+
====================================
33

44
You can Use the :command:`config` subcommand to list or validate your current settings.
55

66
Listing Configuration
7-
~~~~~~~~~~~~~~~~~~~~~
7+
---------------------
88

99
To see the current merged configuration:
1010

@@ -15,7 +15,7 @@ To see the current merged configuration:
1515
Use the ``--flat`` flag to see the dotted-path format, or filter by ``--app`` or ``--env``.
1616

1717
Validating Configuration
18-
~~~~~~~~~~~~~~~~~~~~~~~~
18+
------------------------
1919

2020
To ensure your TOML files match the required schema:
2121

‎docs/source/user/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ User Guide
77

88
install
99
config
10+
portal-config/index
1011
run-docbuild
1112
config/index
1213
build

‎docs/source/user/portal-config/add-deliverable.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
.. _add-deliverable:
2+
3+
Adding a Deliverable
4+
====================
5+
6+
A deliverable is a documentation output that docbuild will
7+
either build from source or take as a prebuilt file and
8+
publish on the portal:
9+
10+
* Build from source
11+
12+
A deliverable that is built by :command:`daps` from a DocBook XML
13+
or ADoc source file. It needs a DC file.
14+
15+
.. code-block:: xml
16+
:caption: Example of a Deliverable Built from Source
17+
18+
<deliverable type="dc" id="nas.1.0.overview">
19+
<dc file="DC-NAS-overview">
20+
<format epub="0" html="1" pdf="1" single-html="1" />
21+
</dc>
22+
</deliverable>
23+
24+
* Prebuilt file
25+
26+
A deliverable that is already built and available as a file.
27+
It can be used for example for documentation that is not in
28+
DocBook XML or ADoc format or for documentation that is built
29+
by a different tool than :command:`daps`:
30+
31+
.. code-block:: xml
32+
:caption: Example of a Prebuilt Deliverable
33+
34+
<deliverable id="cn.continuous-delivery.latest-en-index.overview" type="prebuilt" category="cat.cloudnative.rancher">
35+
<prebuilt>
36+
<title>Overview</title>
37+
<url format="html" href="/cloudnative/continuous-delivery/latest/en/index.html"/>
38+
</prebuilt>
39+
</deliverable>
40+
41+
* Translations
42+
43+
A deliverable that is a translation of an existing deliverable.
44+
It is linked to the original deliverable:
45+
46+
.. code-block:: xml
47+
:caption: Example of a Translated Deliverable
48+
49+
<deliverable type="ref">
50+
<ref linkend="nas.1.0.overview"/>
51+
</deliverable>
52+
53+
54+
To add a deliverable, proceed as follows:
55+
56+
#. Identify the release you want to add the deliverable to.
57+
58+
If you haven't created a release yet, create one as described in
59+
section :ref:`create-product`.
60+
61+
In this example, we want to add a deliverable to the 1.0
62+
release of the NAS product.
63+
64+
#. Create a deliverable.
65+
66+
In our example, we have a DocBook XML source and a DC file :file:`DC-NAS-overview`. We want to build HTML, PDF, and
67+
single HTML output, but not EPUB:
68+
69+
.. code-block:: xml
70+
:caption: Example of a Deliverable Built from Source
71+
72+
<deliverable type="dc" id="nas.1.0.overview">
73+
<dc file="DC-NAS-overview">
74+
<format epub="0" html="1" pdf="1" single-html="1" />
75+
</dc>
76+
</deliverable>
77+
78+
#. Add as many deliverables as needed.

‎docs/source/user/portal-config/add-translations.rst‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. _add-translations:
2+
3+
Adding Translations
4+
===================
5+
6+
To add translations for a product, proceed as follows:
7+
8+
#. Identify the product and release you want to add the translations to.
9+
10+
If you haven't created a release yet, create one as described in
11+
section :ref:`create-product`.
12+
13+
#. Open the file with the configuration for the release.
14+
15+
In our example, we want to add translations for the example
16+
:file:`1.0.xml` for the 1.0 release of the NAS product.
17+
18+
#. Add a ``<locale>`` element for the language you want to
19+
add the translation for.
20+
21+
For example, to add a translation for German , add a
22+
``<locale>`` element with the ``lang`` attribute set to ``de-de``:
23+
24+
.. code-block:: xml
25+
:caption: Adding a Locale Element for German
26+
:name: locale
27+
28+
<locale lang="de-de">
29+
<branch>translations</branch>
30+
<subdir>l10n/de-de</subdir>
31+
<!-- ... translated deliverables ... -->
32+
</locale>
33+
34+
As translations are usually stored in a separate Git branch and
35+
perhaps also in a different directory, the ``<locale>`` element
36+
provides an optional ``<branch>`` and ``<subdir>`` element.
37+
38+
39+
#. Add translated deliverables.
40+
41+
For translated deliverables, use a ``<deliverable>`` element
42+
with ``type="ref"`` and a ``<ref>`` element like this:
43+
44+
.. code-block:: xml
45+
:caption: Adding a Translated Deliverable
46+
:name: translated-deliverable
47+
48+
<deliverable type="ref">
49+
<ref linkend="nas.1.0.overview"/>
50+
</deliverable>
51+
52+
The ``linkend`` attribute of the ``<ref>`` element
53+
points to the ID of the original deliverable.

0 commit comments

Comments
 (0)