Skip to content

Commit 36228fd

Browse files
krisdalerscohn2
krisdale
authored and
rscohn2
committed
Update README AND CONTRIBUTING (#261)
- General editorial/capitalization/readability edits - Standardize capitalization in section headings - Add local TOC for easier navigation - Add contribute and license section to README - Move guidance for contributing (re editing, etc) to CONTRIBUTING - Move build instructions into Build the Specification section - Some reorganization of content for consistency and readability Signed-off-by: Kristal Dale <[email protected]>
1 parent 5e9a665 commit 36228fd

File tree

2 files changed

+141
-117
lines changed

2 files changed

+141
-117
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 85 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
.. SPDX-License-Identifier: CC-BY-4.0
44
55
=================
6-
How to contribute
6+
How to Contribute
77
=================
88

99
This specification is a continuation of Intel’s decades-long history
@@ -21,43 +21,41 @@ prohibit you from also contributing your feedback directly to other
2121
standard bodies, including The Khronos Group under their respective
2222
submission policies.
2323

24-
Contribute to the oneAPI Specification by opening issues in the oneAPI
25-
Specification `GitHub repository
26-
<https://github.com/oneapi-src/oneapi-spec>`__.
24+
.. contents::
25+
:local:
26+
:depth: 1
2727

2828
----------
2929
Governance
3030
----------
3131

32-
See `governance <doc/governance.rst>`__.
32+
See `governance <doc/governance.rst>`__ for more information.
3333

34-
----------------
35-
General Feedback
36-
----------------
34+
---------------
35+
Submit a Change
36+
---------------
3737

38-
Questions and feature requests can be submitted as issues in the `GitHub repository
39-
<https://github.com/oneapi-src/oneapi-spec>`__. Writing changes can be submitted as
40-
an issue or a pull request. See the the next section on how to submit changes. If
41-
none of these methods are appropriate, you may also email to
42-
`[email protected] <mailto:[email protected]>`__.
38+
* For questions, feature requests, or to report a bug, submit an
39+
`issue <https://github.com/oneapi-src/oneAPI-spec/issues>`__.
40+
* For changes to the document build infrastructure or minor editing of the text,
41+
please submit a `pull request <https://github.com/oneapi-src/oneAPI-spec/pulls>`__.
42+
* For significant changes to the specification, submit an
43+
`issue <https://github.com/oneapi-src/oneAPI-spec/issues>`__. Make sure to
44+
45+
* include "RFC" in the title,
46+
* explain your proposed change and the motivation for the change.
4347

44-
------------------
45-
Submitting changes
46-
------------------
48+
You may also create a pull request as a way to explain the change.
4749

48-
For changes to the infrastructure to build the document or minor
49-
editing/rewriting of the text, please submit a pull request. For
50-
significant changes to the specification, first submit an issue with
51-
RFC in the title. Explain what you want to change and the
52-
motivation. You may also create a pull request as a way to explain the
53-
change.
50+
If none of these methods are appropriate, you may also email
51+
`[email protected] <mailto:[email protected]>`__.
5452

5553
--------------
56-
Sign your work
54+
Sign Your Work
5755
--------------
5856

59-
Please include a signed-off-by tag in every contribution of
60-
your feedback. By including a signed-off-by tag, you agree
57+
Please include a signed-off-by tag in every contribution of
58+
your feedback. By including a signed-off-by tag, you agree
6159
that:
6260

6361
1. You have a right to license your feedback to Intel.
@@ -69,8 +67,68 @@ that:
6967
3. Your feedback will be public and that a record of your feedback
7068
may be maintained indefinitely.
7169

72-
If you agree to the above, every contribution of your feedback
73-
must include the following line using your real name and email
70+
If you agree to the above, every contribution of your feedback
71+
must include the following line using your real name and email
7472
address: Signed-off-by: Joe Smith [email protected]
7573

74+
-----------
75+
Style Guide
76+
-----------
77+
78+
See the `oneAPI Specification Style Guide <style-guide.rst>`_ for information.
79+
80+
----------------------------------
81+
Edit with the GitHub Web Interface
82+
----------------------------------
83+
84+
The simplest and quickest way to submit an edit is via the GitHub web
85+
interface. It provides an editor, change preview, and lets you submit the change
86+
as a pull request. You won't need to install any local tools. The preview will
87+
render ReST, but not the Sphinx directives, so it will not display exactly as the
88+
final document.
89+
90+
----------------------
91+
Work with a Local Copy
92+
----------------------
93+
94+
For bigger edits you will need a local version of the tools. See
95+
:ref:`Build the Specification <build_spec>` for instructions.
96+
97+
-------------
98+
Editing Tools
99+
-------------
100+
101+
For simple edits to individual files, you can use the GitHub web
102+
interface.
103+
104+
**Emacs** has a built-in ReST mode. It does some syntax highlighting and
105+
helps with some of the tedious aspects of ReST. M-q will rejustify
106+
long lines to fit the recommended 80 character line. It understands
107+
ReST formatting and won't mess up lists. C-= is a Swiss army knife. It
108+
will cycle between different characters for a section break adornment
109+
(e.g. --, ===, ...) It will make the section break adornment match the
110+
size of the text. Probably a lot more.
111+
112+
**Visual Studio Code** has extensions for previewers and automatic
113+
linting. I could not find any support for rejustifying paragraphs to
114+
80 characters, which makes it difficult to use.
115+
116+
-----------------------------
117+
Create a New Version Number
118+
-----------------------------
119+
120+
Change version in `<oneapi-doc.json>`__ and update the table in
121+
`<source/versions.rst>`__.
122+
123+
------------
124+
More Reading
125+
------------
126+
127+
* `Sphinx Documentation <http://www.sphinx-doc.org/en/master/>`_
128+
* `reStructuredText docs`_: User and reference manuals.
129+
* `Online editor/viewer`_: Web page that lets you type in some rst fragments
130+
and view. Good for debugging.
131+
132+
.. _`reStructuredText docs`: http://docutils.sourceforge.net/rst.html
133+
.. _`online editor/viewer`: http://rst.aaroniles.net/
76134

‎README.rst‎

Lines changed: 56 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -9,153 +9,119 @@ oneAPI Specifications
99
.. image:: https://github.com/oneapi-src/oneapi-spec/workflows/CI/badge.svg
1010
:target: https://github.com/oneapi-src/oneapi-spec/actions?query=workflow%3ACI
1111

12-
This repo contains the sources for the `oneAPI Specification`_.
12+
This repository contains the sources for the `oneAPI Specification`_. For the
13+
latest build from main branch, see
14+
`HTML <https://oneapi-src.github.io/oneAPI-spec>`__ and
15+
`PDF <https://rscohn2.github.io/oneAPI-spec/oneAPI-spec.pdf>`__.
1316

14-
For the latest build from main branch, see `HTML
15-
<https://oneapi-src.github.io/oneAPI-spec>`__ and `PDF
16-
<https://rscohn2.github.io/oneAPI-spec/oneAPI-spec.pdf>`__.
17+
For more information about oneAPI, see
18+
`oneapi.com <https://oneapi.com>`__. For information about future releases of the
19+
oneAPI specification, see the `oneAPI Specification Roadmap <roadmap.rst>`__.
20+
To be notified about new releases, become a release-only watcher of this
21+
repo.
1722

18-
For more information about oneAPI, see `oneapi.com
19-
<https://oneapi.com>`__. For information about future releases of the
20-
oneAPI specification, see the `roadmap <roadmap.rst>`__. To be
21-
notified about new releases, become a release-only watcher of this
22-
repo. See `contribute <CONTRIBUTING.rst>`__ for information about
23-
contributing.
23+
The document is written using `reStructuredText`_ and built with `Sphinx`_ using
24+
a theme provided by `Read the Docs`_.
2425

25-
The document is built with `Sphinx`_ using a theme provided by `Read
26-
the Docs`_.
26+
.. contents::
27+
:local:
28+
:depth: 1
2729

28-
---------------------------------
29-
Editing with GitHub Web Interface
30-
---------------------------------
30+
-------
31+
License
32+
-------
3133

32-
The simplest and quickest way to edit is directly in the GitHub web
33-
interface. It has an editor, previewer, and lets you commit
34-
changes. You won't need to install any local tools. The previewer
35-
knows how to render RST, but not the sphinx directives so it will not
36-
display exactly as the real document.
34+
The oneAPI specification is licensed under the Creative Commons Attribution 4.0
35+
International License.
3736

38-
-------------------------
39-
Working with a Local Copy
40-
-------------------------
37+
See `LICENSE <LICENSE.rst>`__ for more information.
4138

42-
For bigger edits, you will need a local version of the tools. Clone
43-
this repo to your local system. scripts/oneapi.py is a helper script
44-
for the maintenance tasks. You can also look at the source if you want
45-
to do the same task manually.
39+
----------
40+
Contribute
41+
----------
42+
43+
See `CONTRIBUTING <CONTRIBUTING.rst>`__ for more information.
44+
45+
.. _build_spec:
46+
47+
-----------------------
48+
Build the Specification
49+
-----------------------
50+
51+
To build the specification document locally, clone this repository to your local
52+
system and follow the setup and build instructions. The setup and build steps
53+
make use of scripts/oneapi.py, a helper script for maintenance tasks. You can
54+
also look at the source if you want to see how to do the same task manually.
4655

4756
Setup
4857
-----
4958

50-
Install Python 3, doxygen (>= 1.8.17), latex, etc. To install on **Ubuntu**::
59+
Install Python 3, Doxygen (>= 1.8.17), LaTeX, etc. To install on **Ubuntu**::
5160

5261
sudo scripts/install.sh
5362

5463
Create and activate a Python virtual environment with all required tools::
5564

5665
python scripts/oneapi.py spec-venv
5766
source spec-venv/bin/activate
58-
67+
5968
To install directly with pip::
6069

6170
pip install -r requirements.txt
6271

63-
On Windows::
72+
To install on Windows::
6473

6574
python scripts\oneapi.py spec-venv
6675
spec-venv\Scripts\activate
67-
6876

69-
Building the docs
70-
-----------------
77+
Build the Docs
78+
--------------
7179

72-
To build the html document::
80+
To build the HTML document, use the following command::
7381

7482
python scripts/oneapi.py html
7583

7684
The document is organized as a book with chapters. Each element of
7785
oneAPI is its own chapter and can be built separately. For example, to
78-
build the oneVPL chapter, do::
86+
build the oneVPL chapter, use the following command::
7987

8088
python scripts/oneapi.py html source/elements/oneVPL
81-
82-
To see the docs, visit build/html/index.html in your browser using a
83-
file:// URL. Build the pdf version with::
84-
85-
python scripts/oneapi.py latexpdf
86-
87-
And then view build/latexpdf/oneAPI-spec.pdf
88-
89-
Editing Tools
90-
-------------
9189

92-
For simple edits to individual files, you can use the GitHub web
93-
interface.
90+
To view the HTML docs, visit build/html/index.html in your browser using a
91+
file:// URL.
9492

95-
**Emacs** has a built-in ReST mode. It does some syntax highlighting and
96-
helps with some of the tedious aspects of ReST. M-q will rejustify
97-
long lines to fit the recommended 80 character line. It understands
98-
ReST formatting and won't mess up lists. C-= is a Swiss army knife. It
99-
will cycle between different characters for a section break adornment
100-
(e.g. --, ===,...) It will make the section break adornment match the
101-
size of the text. Probably a lot more.
93+
Build the pdf version wit the following command::
10294

103-
**Visual Studio Code** has extensions for previewers and automatic
104-
linting. I could not find any support for rejustifying paragraphs to
105-
80 characters, which makes it difficult to use.
106-
107-
------------------
108-
Submitting changes
109-
------------------
95+
python scripts/oneapi.py latexpdf
11096

111-
Changes are submitted as PR's to this repo. PR's and push trigger the
112-
CI to build the doc and save it as an artifact. If you are working in
113-
a fork on github, commits to the main branch will build and publish
114-
the doc in the github pages associated with the repo.
97+
The generated PDF will be located at build/latexpdf/oneAPI-spec.pdf.
11598

116-
------
11799
Docker
118100
------
119101

120-
You can build a **Docker container** image with::
102+
You can build a **Docker container** image with the following command::
121103

122104
python scripts/oneapi.py dockerbuild
123105

124106
The tag will be rscohn2/oneapi-spec. The script copies your proxy settings in
125107
the invoking shell so it will work inside the firewall.
126108

127-
You can run a docker container with::
109+
You can run a docker container with the following command::
128110

129111
python scripts/oneapi.py dockerrun
130112

131113
--
132114
CI
133115
--
134116

135-
We use GitHub actions. See `<.github/workflows/ci.yml>`_
136-
117+
We use GitHub actions. See `<.github/workflows/ci.yml>`_.
137118

138-
-----------------------------
139-
Creating a new version number
140-
-----------------------------
119+
PR's trigger the CI to build the document and save it as an artifact. If you are
120+
working in a fork on GitHub, commits to the main branch will build and publish
121+
the document in the GitHub pages associated with the repository.
141122

142-
Change version in `<oneapi-doc.json>`__ and update the table in
143-
`<source/versions.rst>`__.
144123

145-
------------
146-
More Reading
147-
------------
148-
149-
* `oneAPI Specification Roadmap <roadmap.rst>`__
150-
* `oneAPI Specification Style Guide <style-guide.rst>`_
151-
* `Sphinx Documentation <http://www.sphinx-doc.org/en/master/>`_
152-
* `rst docs`_: User and reference manuals.
153-
* `online editor/viewer`_: Web page that lets you type in some rst fragments
154-
and view. Good for debugging.
155-
156-
.. _`rst tutorial`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
157-
.. _`rst docs`: http://docutils.sourceforge.net/rst.html
158-
.. _`online editor/viewer`: http://rst.aaroniles.net/
159-
.. _`oneAPI Specification`: https://spec.oneapi.com
124+
.. _`reStructuredText`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
160125
.. _`Sphinx`: http://www.sphinx-doc.org/en/master/
161126
.. _`Read the Docs`: https://readthedocs.org/
127+
.. _`oneAPI Specification`: https://spec.oneapi.com

0 commit comments

Comments
 (0)