blob: 33803c98a262d2330c2c5749cded026181a457f7 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
.. _documentation:
Documentation
=============
As most software projects we also have a lack in documentation. We encourage
every VyOS user to help us improve our documentation. This will not only be
benefical four you (when reading something up) but also for the whole world.
If you are willing to contribute to our documentation this is the definate
guid how to do so.
.. note:: In contrast to submitting code patches there is no requirement that
you open up a Phabricator_ task prior to submitting a Pull-Request to the
documentation.
Git Workflow
------------
Updates to our documentation should be delivered by a GitHub pull-request. In
order to create a pull-request you need to fork our documentation code first.
This requires you already have a GitHub account.
* Fork the project on GitHub https://github.com/vyos/vyos-documentation/fork
* Clone fork to local machine
* Change to your new local directory ``vyos-documentation``
* Create new branch for your work, use a descriptive name of your work:
``$ git checkout -b fix-vxlan-typo``
* Make all your changes - please keep out commit rules in mind
(:ref:`prepare_commit`). This mainly applies to a proper commit message
describing your change. Please check the documentation if you aren't familiar
with Sphinx-doc_ or reStructuredText_.
* Check your changes by locally building the documentation ``$ make html``
Sphinx will build the html files in the ``docs/_build`` folder
* Add modified files to Git index ``$ git add path/to/filname`` or add all
unstaged files ``$ git add .``
* Commit your changes ``$ git commit -m "vxlan: rework CLI syntax"``
* Push your commits to your GitHub project: ``$ git push -u origin
fix-vxlan-typo``
* Submit pull-request. In GitHub visit the main repository and you should
see a banner suggesting to make a pull request. Fill out the form and
describe what you do.
* Once pull resquests have been approved, you may want to locally update
your forked repository too. First you'll have to add the remote upstream
repository. ``$ git remote add upstream
https://github.com/vyos/vyos-documentation.git``
Check your configured remote repositories:
.. code-block:: sh
$ git remote -v
origin https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch)
origin https://github.com/YOUR_USERNAME/vyos.documentation.git (push)
upstream https://github.com/vyos/vyos-documentation.git (fetch)
upstream https://github.com/vyos/vyos-documentation.git (push)
Your remote repo on Github is called Origin, while the original repo you
have forked is called Upstream. Now you can locally update your forked repo.
.. code-block:: sh
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
If you want to update your fork on GitHub, too use the following:
``$ git push origin master``
Style Guide
-----------
Sections
^^^^^^^^
We use the following syntax for Headlines.
.. code-block:: sh
#####
Parts
#####
********
Chapters
********
Sections
========
Subsections
-----------
Subsubsections
^^^^^^^^^^^^^^
Paragraphs
""""""""""
Address space
^^^^^^^^^^^^^
Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and
:rfc:`7042`), which describe the reserved public IP addresses and autonomous
system numbers for the documentation:
* ``192.0.2.0/24``
* ``198.51.100.0/24``
* ``203.0.113.0/24``
* ``2001:db8::/32``
* 16bit ASN: ``64496 - 64511``
* 32bit ASN: ``65536 - 65551``
* Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF``
* Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF``
Please don't use other public address space.
Specific Sphinx-doc Markup
^^^^^^^^^^^^^^^^^^^^^^^^^^
When documenting CLI commands use the ``.. cfgcmd::`` directive for
the configuration mode and the ``.. opcmd::`` directive for operational mode
commands.
Under the command a short exlaination should be provide.
Example:
.. code-block:: sh
.. opcmd:: show protocols static arp
Display all known ARP table entries spanning accross all interfaces
.. _Sphinx-doc: https://www.sphinx-doc.org
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _Phabricator: https://phabricator.vyos.net
|
