Welcome to sphinx.rfc2119’s documentation!

Contents:

Introduction

The purpose of this sphinx extension is enable markup of requirements per the definitions in RFC 2119.

This is supported by a suite of requirement directives that correspond to the RFC 2119 keywords. There are also a suite of requirement list directives that support documenting reqiurements (that have been defined with the rfc2119 directives).

This module is in ALPHA status. Feedback / pull requests very welcome. Development occurs on GitHub:

Documentation is a bit strange - I used the directives to document what it is supposed to do. Which was handy as I made it, but probably not very readable.

Basically, add the module to your the conf.py of your repo then use the directives. They have lower case names.

The motivtion for this module is in response to this ticket:

Must

As per RFC 2119, users of this module should include a block of boilerplate near the beginning of their sphinx document. A rfc2119interpretation directive is required for this purpose.

RFC 2119 keywords

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

May

Optionally, this module should support governance parameters for documenting requirement status, valid from date, review date, etc.

None of these features are implemented yet, sorry. If there’s something you actually need, please raise a ticket on GitHub.

Requirement Directives

RFC 2119 defines:
  • 5 mandatory requirement labels
  • 5 recommendation labels
  • 2 optional labels

This sphinx extension includes 12 coresponding “requirements directives”. They have lowercase names (with words separated by underscores for two word phrases.

Mandatory Requirements

Must

A must directive is required, with semantic equivalence to the MUST keyword in RFC 2119.

Must Not

The absence of a must_not directive is forbidden. This directive has semantic equivalence to the MUST NOT keyword in RFC 2119

Shall

A shall directive is required. It is an alias for the must directive.

Shall Not

The absence of a shall_not directive is forbidden. It is a necessary alias for the must_not directive.

Required

A required directive is something we need. It is an alias for the must directive.

Recommendations

Should

A should directive is important. It has semantic equivalence to the SHOULD keyword in RFC 2119.

Should Not

The absence of a should_not directive is not something we want. It is equivalent to the SHOULD NOT key word in RFC 2119.

Options

Optional

It might be nice to have an optional directive, which would be equivalent of OPTIONAL keyword in RFC 2119.

May

As an alias for the optional directive, a may directive might also be good to have.

Requirement List Directives

Must

A mandatorylist directive is required. It should produce a list of all MUST and MUST NOT directives (and their aliases).

Must

A recommendedlist directive is required. It should produce a list of all SHOULD and SHOULD NOT directives (and their aliases).

Must

A optionallist directive is required. It should produce a list of all OPTIONAL and MAY directives.

Example Mandatory List

The following list of mandatory reqirements includes every MUST, MUST NOT, SHALL, SHALL NOT and REQUIRED semantic in this suite of documentation, because they are makted up with the appropriate directives.

Must

As per RFC 2119, users of this module should include a block of boilerplate near the beginning of their sphinx document. A rfc2119interpretation directive is required for this purpose.

(The original entry is located in introduction.rst, line 24 and can be found here.)

Must

A must directive is required, with semantic equivalence to the MUST keyword in RFC 2119.

(The original entry is located in requirement_directives.rst, line 17 and can be found here.)

Must Not

The absence of a must_not directive is forbidden. This directive has semantic equivalence to the MUST NOT keyword in RFC 2119

(The original entry is located in requirement_directives.rst, line 23 and can be found here.)

Shall

A shall directive is required. It is an alias for the must directive.

(The original entry is located in requirement_directives.rst, line 30 and can be found here.)

Shall Not

The absence of a shall_not directive is forbidden. It is a necessary alias for the must_not directive.

(The original entry is located in requirement_directives.rst, line 36 and can be found here.)

Required

A required directive is something we need. It is an alias for the must directive.

(The original entry is located in requirement_directives.rst, line 42 and can be found here.)

Must

A mandatorylist directive is required. It should produce a list of all MUST and MUST NOT directives (and their aliases).

(The original entry is located in requirement_list_directives.rst, line 4 and can be found here.)

Must

A recommendedlist directive is required. It should produce a list of all SHOULD and SHOULD NOT directives (and their aliases).

(The original entry is located in requirement_list_directives.rst, line 10 and can be found here.)

Must

A optionallist directive is required. It should produce a list of all OPTIONAL and MAY directives.

(The original entry is located in requirement_list_directives.rst, line 17 and can be found here.)

Must

As per RFC 2119, users of this module should include a block of boilerplate near the beginning of their sphinx document. A rfc2119interpretation directive is required for this purpose.

(The original entry is located in introduction.rst, line 24 and can be found here.)

Example Optional List

Optional

It might be nice to have an optional directive, which would be equivalent of OPTIONAL keyword in RFC 2119.

(The original entry is located in requirement_directives.rst, line 78 and can be found here.)

May

As an alias for the optional directive, a may directive might also be good to have.

(The original entry is located in requirement_directives.rst, line 84 and can be found here.)

May

Optionally, this module should support governance parameters for documenting requirement status, valid from date, review date, etc.

None of these features are implemented yet, sorry. If there’s something you actually need, please raise a ticket on GitHub.

(The original entry is located in introduction.rst, line 35 and can be found here.)

Code

class sphinx_rfc2119.MandatoryListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
has_content = True
run()[source]
class sphinx_rfc2119.MayDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'May'
requirement_class = 'optional'
class sphinx_rfc2119.MustDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Must'
requirement_class = 'mandatory'
class sphinx_rfc2119.MustNotDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Must Not'
requirement_class = 'mandatory'
class sphinx_rfc2119.NotRecommendedDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Not Recommended'
requirement_class = 'recommendation'
class sphinx_rfc2119.OptionalDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Optional'
requirement_class = 'optional'
class sphinx_rfc2119.OptionalListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
has_content = True
run()[source]
class sphinx_rfc2119.RecommendationListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
has_content = True
run()[source]
class sphinx_rfc2119.RecommendedDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Recommended'
requirement_class = 'recommendation'
class sphinx_rfc2119.RequiredDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Required'
requirement_class = 'mandatory'
class sphinx_rfc2119.ShallDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Shall'
requirement_class = 'mandatory'
class sphinx_rfc2119.ShallNotDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Shall Not'
requirement_class = 'mandatory'
class sphinx_rfc2119.ShouldDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Should'
requirement_class = 'recommendation'
class sphinx_rfc2119.ShouldNotDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
label = 'Should Not'
requirement_class = 'recommendation'
sphinx_rfc2119.depart_rfc2119_node(self, node)[source]
class sphinx_rfc2119.mandatory(rawsource='', *children, **attributes)[source]
class sphinx_rfc2119.mandatorylist(rawsource='', *children, **attributes)[source]
class sphinx_rfc2119.optional(rawsource='', *children, **attributes)[source]
class sphinx_rfc2119.optionallist(rawsource='', *children, **attributes)[source]
sphinx_rfc2119.process_rfc2119_nodes(app, doctree, fromdocname)[source]
sphinx_rfc2119.purge_rfc2119_mandatory(app, env, docname)[source]
sphinx_rfc2119.purge_rfc2119_optional(app, env, docname)[source]
sphinx_rfc2119.purge_rfc2119_recommendation(app, env, docname)[source]
class sphinx_rfc2119.recommendationlist(rawsource='', *children, **attributes)[source]
class sphinx_rfc2119.recommended(rawsource='', *children, **attributes)[source]
class sphinx_rfc2119.rfc2119Directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

An abstract base for rfc2199 requirements.

has_content = True
label = 'rfc2119'
requirement_class = 'rfc2119'
run()[source]
class sphinx_rfc2119.rfc2119InterpretationDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
has_content = False
run()[source]
class sphinx_rfc2119.rfc2119interpretation(rawsource='', *children, **attributes)[source]
sphinx_rfc2119.setup(app)[source]
sphinx_rfc2119.visit_rfc2119_node(self, node)[source]

Indices and tables