Skip to content

Commit af62e4a

Browse files
authored
Merge pull request italia#665 from pcerqua-ipzs/warning-removal
Editorials, RST Sphinx Build Improvements and Contributing Section
2 parents 761b0e8 + e94cd3b commit af62e4a

File tree

64 files changed

+6972
-6597
lines changed

Some content is hidden

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

64 files changed

+6972
-6597
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Thumbs.db
1414
html
1515
env
1616
build
17+
latex
1718
env-preview
1819
.venv
1920
.vscode

CONTRIBUTING-RULES.md

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# Contributing Rules
2+
3+
This guide provides guidelines for contributing to IT-Wallet Technical Documentation. Following these conventions ensures consistency across all documentation files.
4+
5+
## Table of Contents
6+
7+
- [Contributing Rules](#contributing-rules)
8+
- [Table of Contents](#table-of-contents)
9+
- [General Formatting and Editorial Conventions](#general-formatting-and-editorial-conventions)
10+
- [File Organization](#file-organization)
11+
- [Section Headers](#section-headers)
12+
- [Cross-References](#cross-references)
13+
- [Internal References](#internal-references)
14+
- [Referencing External Resources](#referencing-external-resources)
15+
- [Referencing RFC Documents](#referencing-rfc-documents)
16+
- [Important Syntax Notes](#important-syntax-notes)
17+
- [Figures and Images](#figures-and-images)
18+
- [Image Requirements](#image-requirements)
19+
- [Cross-Referencing Figures](#cross-referencing-figures)
20+
- [Tables](#tables)
21+
- [Table Requirements](#table-requirements)
22+
- [Row and Cell Formatting](#row-and-cell-formatting)
23+
- [Cross-Referencing Tables](#cross-referencing-tables)
24+
- [Non-Normative Examples](#non-normative-examples)
25+
- [Inline Code Examples](#inline-code-examples)
26+
- [External Code Files](#external-code-files)
27+
- [Notes and Warnings](#notes-and-warnings)
28+
29+
## General Formatting and Editorial Conventions
30+
31+
- **Encoding**: Files should be saved with UTF-8 encoding
32+
- **Technical parameter names**, such as JSON fileds or HTTP parameters, must be enclosed in double backticks, i.e.: ``client_id``, ``redirect_uri``, ``authorization_details``.
33+
- **Example URLs** in non-normative examples must use not real domains (such as ``example.org``, ``wallet-provider.example.org``) and must not reference real production URLs
34+
- **File and path names**, use lowercase, and be separated by hyphens: ``credential-issuance.rst``, ``credential-issuance-endpoint.rst``
35+
- **Titles**, use Title Case Style: Capitalize all major words in titles. Major words exclude articles (a, an, the), prepositions (on, in, of, etc.), coordinating conjunctions (and, or, but, etc.), and 'to'.
36+
37+
## File Organization
38+
39+
When creating multiple RST files:
40+
41+
1. Create a main index file (e.g., `credential-issuance.rst`)
42+
2. Use the `toctree` directive to organize related files:
43+
44+
```rst
45+
.. toctree::
46+
:caption: Table of Contents
47+
:maxdepth: 3
48+
49+
credential-issuance-high-level.rst
50+
credential-issuance-low-level.rst
51+
credential-issuance-endpoint.rst
52+
```
53+
54+
Parameters:
55+
- `:caption:` - add a caption to the toctree
56+
- `:maxdepth:` - the depth level to display in the table of contents
57+
58+
## Section Headers
59+
60+
Use the following characters for section levels, maintaining this hierarchy:
61+
62+
```
63+
Equal signs (=) for Sections
64+
============================
65+
66+
Hyphens (-) for Subsections
67+
---------------------------
68+
69+
Carets (^) for Subsubsections
70+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
71+
72+
Double quotes (") for Paragraphs
73+
"""""""""""""""""""""""""""""""
74+
75+
Dots (.) for Subparagraphs
76+
..........................
77+
```
78+
79+
Section headers must have the same number of underline/overline characters as at least the length of the header text.
80+
81+
## Cross-References
82+
83+
### Internal References
84+
85+
This Technical Documentation uses `sphinx.ext.autosectionlabel` with `autosectionlabel_prefix_document` set to `True`.
86+
87+
Therefore, for cross-referencing within documents, use the `:ref:` role with the name of the document in which the section is referenced and the section tile, separated by a colon:
88+
89+
```rst
90+
See :ref:`file-name:Section Title`.
91+
```
92+
93+
#### Referencing External Resources
94+
95+
To reference external resources in your documentation:
96+
97+
1. **Basic reference** - use underscore suffix:
98+
```rst
99+
See `OpenID4VCI`_ for more information.
100+
```
101+
102+
2. **Reference to specific section** - include section information:
103+
```rst
104+
See Section 7.2 of [`OpenID4VCI`_].
105+
```
106+
107+
#### Referencing RFC Documents
108+
109+
RFC documents use a special role syntax that differs from regular external references:
110+
111+
```rst
112+
As defined in :rfc:`7519`.
113+
```
114+
115+
You can also reference specific sections within RFCs:
116+
117+
```rst
118+
See :rfc:`6749#section-4.1.2.1`.
119+
```
120+
121+
These references will automatically link to the appropriate RFC document without needing an entry in `common_definitions.rst`.
122+
123+
#### Important Syntax Notes
124+
125+
- The reference name (e.g., `OpenID4VCI`) is case-sensitive
126+
- The trailing underscore (`_`) is required in the reference usage
127+
- When using brackets, the backtick+text+backtick+underscore combination must be exact: [`text`_]
128+
- Always use backticks (`) and not single quotes (') around reference names
129+
- Reference definitions in `common_definitions.rst` start with `.. _` (dot dot space underscore)
130+
- Avoid duplicate reference names as they will cause build warnings
131+
132+
## Figures and Images
133+
134+
Use the `figure` directive for images, preferably in SVG format for diagrams:
135+
136+
```rst
137+
.. _fig_reference_name:
138+
.. figure:: ../../images/diagram-name.svg
139+
:figwidth: 90%
140+
:align: center
141+
:target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
142+
143+
Caption text describing the figure.
144+
```
145+
146+
### Image Requirements
147+
148+
- **Format**: All images must be in SVG format for optimal rendering and scalability
149+
- **Diagrams**: All architecture, component or sequence diagrams must be created using PlantUML with C4 Component modeling
150+
- **Attributes**:
151+
- `:figwidth:` - REQUIRED (usually specified as percentage, e.g., `90%`)
152+
- `:align:` - REQUIRED (typically `center`)
153+
- Caption text - REQUIRED (appears below the figure)
154+
- `:target:` - REQUIRED for PlantUML diagrams (must link to the PlantUML source)
155+
- Label (e.g., `.. _fig_reference_name:`) - Recommended for cross-referencing but optional. Use the prefix `_fig_` followed by the reference name
156+
157+
When working with figures, understand the difference between these key attributes:
158+
159+
- **:figwidth:** Controls the width of the entire figure block, including the caption and any padding. It defines how much horizontal space the figure occupies in the document layout.
160+
161+
- **:width:** Controls only the width of the image itself, not the entire figure block. Use this when you need to resize just the image while allowing the caption to potentially be wider.
162+
163+
Example with both attributes:
164+
```rst
165+
.. figure:: ../../images/diagram-name.svg
166+
:figwidth: 90% # The entire figure block is 90% of the available width
167+
:width: 80% # The image itself is 80% of the figure block width
168+
:align: center
169+
:target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
170+
171+
This is the caption that appears below the image.
172+
```
173+
174+
Other useful figure attributes:
175+
- **:height:** Controls the height of the image
176+
- **:scale:** Scales the image (e.g., `:scale: 50%`)
177+
- **:alt:** Provides alternative text for accessibility
178+
- **:name:** Used for internal references (can also use the separate label format shown above)
179+
180+
### Cross-Referencing Figures
181+
182+
When a figure has a label defined, you can reference it from anywhere in the documentation:
183+
184+
```rst
185+
As shown in :ref:`fig_reference_name`, the components interact through...
186+
```
187+
188+
This will create a link to the figure with the caption text as the link text.
189+
190+
## Tables
191+
192+
Use the `list-table` directive for tables:
193+
194+
```rst
195+
.. _table_reference_name:
196+
.. list-table:: Table Title
197+
:widths: 20 60 20
198+
:header-rows: 1
199+
200+
* - **Column 1 Header**
201+
- **Column 2 Header**
202+
- **Column 3 Header**
203+
* - Cell 1
204+
- Cell 2
205+
- Cell 3
206+
```
207+
208+
Parameters:
209+
- `:widths:` - relative widths of each column
210+
- `:header-rows:` - number of header rows (usually 1)
211+
212+
### Table Requirements
213+
214+
- The `list-table` directive must be used for all tables (not grid tables or simple tables)
215+
- Each table should have a label for cross-referencing (e.g., `.. _table_name:`). Use the prefix `_table_` followed by the reference table name
216+
- Each table should have a title
217+
- The following attributes are required:
218+
- `:widths:` - relative widths of each column (must match the number of columns)
219+
- `:header-rows:` - number of header rows (usually 1)
220+
- Headers should be in bold format using double asterisks (`**Header Text**`)
221+
222+
### Row and Cell Formatting
223+
224+
- Each row begins with a `*` character
225+
- Each cell within a row begins with a `-` character
226+
- Cells can contain multiple paragraphs, lists, or other block elements
227+
- For multi-line content in a cell, ensure proper indentation:
228+
229+
```rst
230+
* - Cell 1
231+
- This cell has
232+
multiple lines
233+
of content
234+
- Cell 3
235+
```
236+
237+
### Cross-Referencing Tables
238+
239+
When a table has a label defined, you can reference it from anywhere in the documentation:
240+
241+
```rst
242+
As shown in :ref:`table_reference_name`, the parameters include...
243+
```
244+
245+
This will create a link to the table with the table title as the link text. For more specific references, you can refer to a table with custom text:
246+
247+
```rst
248+
See the :ref:`Table of Credential Offer parameters <table_reference_name>`.
249+
```
250+
251+
## Non-Normative Examples
252+
253+
When providing non-normative examples:
254+
255+
1. Clearly label them as non-normative in the text
256+
2. Store examples in separate files when possible
257+
258+
### Inline Code Examples
259+
260+
For inline code blocks, use:
261+
262+
```rst
263+
.. code-block:: http
264+
265+
GET /authorize?client_id=123&request_uri=urn%3Aietf HTTP/1.1
266+
Host: example.org
267+
```
268+
269+
Specify the appropriate language for syntax highlighting.
270+
271+
### External Code Files
272+
273+
For larger code examples, store them in separate files (under `examples/` directory) and include them using `literalinclude`:
274+
275+
```rst
276+
.. literalinclude:: ../../examples/request-object-header.json
277+
:language: JSON
278+
```
279+
280+
Label non-normative examples explicitly in the surrounding text.
281+
282+
## Notes and Warnings
283+
284+
Use note and warning directives to highlight important information:
285+
286+
```rst
287+
.. note::
288+
This is a note providing additional information.
289+
290+
.. warning::
291+
This is a warning about potential issues.
292+
```
293+
294+
Notes and warnings should be indented with 2 spaces.
295+

CONTRIBUTING.md

Lines changed: 30 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,55 @@
1-
# Contributing to this standard
1+
# Contributing to Technical Documentation
22

3-
🙇‍♀️ Thank you for contributing!
3+
## Introduction
44

5-
We – the maintainers and contributors of this project – understand that a standard like this can only be set in collaboration with as many public technologists, policy makers and interested folk as possible. Thus we appreciate your input, enjoy feedback and welcome improvements to this project and are very open to collaboration.
5+
This document outlines the formal procedures for contributing to the Technical Documentation project. As a national technical specification, this documentation requires rigorous standards of contribution and collaboration to ensure accuracy, completeness, and compliance with relevant regulations.
66

7-
We love issues and pull requests from everyone.
7+
## Official Communication Channels
88

9-
## Problems, suggestions and questions in Issues
9+
Contributors are advised to report issues, propose modifications, or request clarifications through the official GitHub Issue tracking system: [GitHub Issues for publiccode.yml](https://github.com/italia/publiccode.yml/issues). Each submission must adhere to standardized documentation protocols.
1010

11-
Please help development by reporting problems, suggesting changes and asking questions. To do this, you can [create a GitHub Issue](https://help.github.com/articles/creating-an-issue/) for this project in the [GitHub Issues for publiccode.yml](https://github.com/italia/publiccode.yml/issues).
11+
Contributing does not necessarily require modifications to the existing documentation; valuable contributions include identification of inconsistencies, clarification requests, and technical inquiries.
1212

13-
You don't need to change any of our code or documentation to be a contributor!
13+
## Contribution Process
1414

15-
## Documentation and code in Pull Requests
15+
To contribute content or code modifications to the Technical Documentation, adherence to the following protocol is required:
1616

17-
If you want to add to the documentation or code of one of our projects you should make a Pull Request.
17+
### Documentation Submission Requirements
1818

19-
If you never used GitHub, get up to speed with [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) or follow one of the great free interactive courses in the [GitHub learning lab](https://lab.github.com/) on working with GitHub and working with MarkDown, the syntax this project's documentation is in.
19+
Contributions to this project must be submitted via the GitHub Pull Request mechanism. Contributors unfamiliar with GitHub procedures are directed to review the [GitHub Flow documentation](https://guides.github.com/introduction/flow/) or complete relevant training modules in the [GitHub learning lab](https://lab.github.com/).
2020

21-
This project is [licenced CC-0](LICENSE), which essentially means that the project, along with your contributions is in the Public Domain in whatever jusrisdiction possible, and everyone can do whatever they want with it.
21+
This documentation is published under [CC-0 license](LICENSE), designating it as Public Domain content within applicable jurisdictions. All contributions are subject to the same licensing terms.
2222

23-
### 1. Make your changes
23+
### Procedural Guidelines
2424

25-
This project uses the [**GitFlow branching model** and workflow](http://nvie.com/posts/a-successful-git-branching-model/). When you've forked this repository, please make sure to create a feature branch following the GitFlow model.
25+
#### 1. Implementation of Modifications
2626

27-
Add your changes in commits [with a message that explains them](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message). Document choices or decisions you make in the commit message, this will enable everyone to be informed of your choices in the future.
27+
This repository implements the [**GitFlow branching model** and workflow](http://nvie.com/posts/a-successful-git-branching-model/). Contributors must create feature branches in accordance with this model when submitting modifications.
2828

29-
If you are adding code, make sure you've added and updated the relevant documentation and tests before you submit your pull request. Make sure to write tests that show the behaviour of the newly added or changed code.
29+
All changes must be documented with comprehensive [commit messages](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message) detailing:
30+
- The nature of the modification
31+
- Technical justification for the change
32+
- References to relevant standards or requirements
3033

31-
### 2. Pull Request
34+
#### 2. Submission Protocol
3235

33-
When submitting the pull request, please accompany it with a description of the problem you are trying to address and the issue numbers that this Pull Request fixes/addresses.
36+
Pull Requests must include:
37+
- A formal description of the addressed technical issue
38+
- References to corresponding issue numbers
39+
- Confirmation of compliance with documentation standards
3440

35-
### 3. Improve
41+
#### 3. Review Process
3642

37-
All contributions have to be reviewed by someone.
43+
Modifications may require revision based on technical feedback before acceptance. The designated maintainers will provide standardized guidance for necessary improvements.
3844

39-
It could be that your contribution can be merged immediately by a maintainer. However, usually, a new Pull Request needs some improvements before it can be merged. Other contributors (or helper robots) might have feedback. If this is the case the reviewing maintainer will help you improve your documentation and code.
45+
Contributions fulfilling all technical and formal requirements will be integrated into the main documentation.
4046

41-
If your documentation and code have passed human review, it is merged.
47+
#### 4. Acknowledgment of Contribution
4248

43-
### 4. Celebrate
49+
Upon successful integration, contributors will be formally recognized for their technical input to this specification.
4450

45-
Your ideas, documentation and code have become an integral part of this project. You are the Open Source hero we need!
46-
47-
In fact, feel free to open a PR to add your name to the [`AUTHORS`](AUTHORS.md) file and get eternal attribution.
51+
Contributors may submit a Pull Request to add their credentials to the [AUTHORS](AUTHORS.md) file for permanent attribution in accordance with project protocols.
4852

4953
---
5054

51-
For more information on how to use and contribute to this project, please read the [`README`](README.md).
55+
For complete technical specifications and additional contribution guidelines, refer to the [README](README.md) documentation and [Contributing Rules Section](CONTRIBUTING-RULES.md).

README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,8 @@ pandoc -o eid-it-wallet-docs.odt index.html
7676

7777
## How to contribute
7878

79-
If you encounter problems or errors, if you’d like to comment or suggest an edit, don’t hesitate to contribute by submitting a [Pull Requests or raise Issues](CONTRIBUTING.md), or exploring existing issues.
79+
80+
Refer to [Contributing Rules Section](CONTRIBUTING-RULES.md) for an editorial guideline. Don't hesitate to submit [Pull Requests or raise Issues](CONTRIBUTING.md) if you encounter any problems.
8081

8182

8283
## Authors

0 commit comments

Comments
 (0)