Sphinx-CodeLinks¶

Tool: Sphinx-CodeLinks TOOL_SCL

status: in_progress

style: blue_bar

version: 1.0.0.

part of: FE_SCL_DEF, FE_SCL_C, FE_SCL_CPP, FE_SCL_PY, FE_SCL_CMT, FE_SCL_LNK, FE_SCL_RST_EXTRACTION, FE_SCL_CLI_ANALYZE, FE_SCL_CLI_DISCOVER, FE_SCL_CLI_WRITE

Sphinx-CodeLinks is a lightweight solution for enabling traceability between source code and documentation.

Documentation:: https://codelinks.useblocks.com/
Code:: https://github.com/useblocks/sphinx-codelinks

Analysis¶

@startuml

' Nodes definition

file "<size:12>Artifact</size>\n**Sphinx-**\n**CodeLinks**\n**needs.json file**\n<size:10>ART_SCL_NEEDS_JSON</size>" as ART_SCL_NEEDS_JSON [[../tools/sphinx-codelinks/artifacts.html#ART_SCL_NEEDS_JSON]] #LightBlue
rectangle "<size:12>Feature</size>\n**Define new**\n**traceability**\n**objects in**\n**source code**\n<size:10>FE_SCL_DEF</size>" as FE_SCL_DEF [[../tools/sphinx-codelinks/features.html#FE_SCL_DEF]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Traceability**\n**objects are not**\n**detected in**\n**supported**\n**languages**\n<size:10>ERR_SCL_1</size>" as ERR_SCL_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**halucinates**\n**traceability**\n**objects**\n<size:10>ERR_SCL_2</size>" as ERR_SCL_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**C Language**\n**Support**\n<size:10>FE_SCL_C</size>" as FE_SCL_C [[../tools/sphinx-codelinks/features.html#FE_SCL_C]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Traceability**\n**objects are not**\n**detected in C**\n**language**\n<size:10>ERR_SCL_C_1</size>" as ERR_SCL_C_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_C_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**halucinates**\n**traceability**\n**objects in C**\n<size:10>ERR_SCL_C_2</size>" as ERR_SCL_C_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_C_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**C++ Language**\n**Support**\n<size:10>FE_SCL_CPP</size>" as FE_SCL_CPP [[../tools/sphinx-codelinks/features.html#FE_SCL_CPP]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Traceability**\n**objects are not**\n**detected in C++**\n**language**\n<size:10>ERR_SCL_CPP_1</size>" as ERR_SCL_CPP_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CPP_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**halucinates**\n**traceability**\n**objects in C++**\n<size:10>ERR_SCL_CPP_2</size>" as ERR_SCL_CPP_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CPP_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**Python Language**\n**Support**\n<size:10>FE_SCL_PY</size>" as FE_SCL_PY [[../tools/sphinx-codelinks/features.html#FE_SCL_PY]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Traceability**\n**objects are not**\n**detected in**\n**Python language**\n<size:10>ERR_SCL_PY_1</size>" as ERR_SCL_PY_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_PY_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**halucinates**\n**traceability**\n**objects in**\n**Python**\n<size:10>ERR_SCL_PY_2</size>" as ERR_SCL_PY_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_PY_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**Customized**\n**comment styles**\n<size:10>FE_SCL_CMT</size>" as FE_SCL_CMT [[../tools/sphinx-codelinks/features.html#FE_SCL_CMT]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Customized**\n**comment styles**\n**are not**\n**detected in**\n**supported**\n**languages**\n<size:10>ERR_SCL_CMT</size>" as ERR_SCL_CMT [[../tools/sphinx-codelinks/features.html#ERR_SCL_CMT]] #Pink
}
rectangle "<size:12>Feature</size>\n**Link code to**\n**existing need**\n**items**\n<size:10>FE_SCL_LNK</size>" as FE_SCL_LNK [[../tools/sphinx-codelinks/features.html#FE_SCL_LNK]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Linking code to**\n**existing need**\n**items fails**\n<size:10>ERR_SCL_LNK_1</size>" as ERR_SCL_LNK_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_LNK_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks links**\n**code to wrong**\n**need items**\n<size:10>ERR_SCL_LNK_2</size>" as ERR_SCL_LNK_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_LNK_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**Extract blocks**\n**of reStructured**\n**Text embedded**\n**within comments**\n<size:10>FE_SCL_RST_EXTRACTION</size>" as FE_SCL_RST_EXTRACTION [[../tools/sphinx-codelinks/features.html#FE_SCL_RST_EXTRACTION]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Extracting reSt**\n**ructuredText**\n**from comments**\n**fails**\n<size:10>ERR_SCL_RST_EXTRACTION_1</size>" as ERR_SCL_RST_EXTRACTION_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_RST_EXTRACTION_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**extracts wrong **\n**reStructuredTex**\n**t blocks**\n<size:10>ERR_SCL_RST_EXTRACTION_2</size>" as ERR_SCL_RST_EXTRACTION_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_RST_EXTRACTION_2]] #Pink
rectangle "<size:12>Error</size>\n**Extracted reStr**\n**ucturedText**\n**blocks are**\n**malformed**\n<size:10>ERR_SCL_RST_EXTRACTION_3</size>" as ERR_SCL_RST_EXTRACTION_3 [[../tools/sphinx-codelinks/features.html#ERR_SCL_RST_EXTRACTION_3]] #Pink
}
rectangle "<size:12>Feature</size>\n**Analyze marked**\n**content via CLI**\n**interface**\n<size:10>FE_SCL_CLI_ANALYZE</size>" as FE_SCL_CLI_ANALYZE [[../tools/sphinx-codelinks/features.html#FE_SCL_CLI_ANALYZE]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**CLI integration**\n**fails silently**\n<size:10>ERR_SCL_CLI_ANALYZE_1</size>" as ERR_SCL_CLI_ANALYZE_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_ANALYZE_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**halucinates**\n**marked content**\n<size:10>ERR_SCL_CLI_ANALYZE_2</size>" as ERR_SCL_CLI_ANALYZE_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_ANALYZE_2]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**misses marked**\n**content**\n<size:10>ERR_SCL_CLI_ANALYZE_3</size>" as ERR_SCL_CLI_ANALYZE_3 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_ANALYZE_3]] #Pink
}
rectangle "<size:12>Feature</size>\n**Discover the**\n**filepaths a**\n**specified root**\n**directory via**\n**CLI interface**\n<size:10>FE_SCL_CLI_DISCOVER</size>" as FE_SCL_CLI_DISCOVER [[../tools/sphinx-codelinks/features.html#FE_SCL_CLI_DISCOVER]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Specifying a**\n**root directory**\n**fails**\n<size:10>ERR_SCL_CLI_DISCOVER_1</size>" as ERR_SCL_CLI_DISCOVER_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_DISCOVER_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**discovers files**\n**outside the**\n**specified root**\n**directory**\n<size:10>ERR_SCL_CLI_DISCOVER_2</size>" as ERR_SCL_CLI_DISCOVER_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_DISCOVER_2]] #Pink
}
rectangle "<size:12>Feature</size>\n**Export marked**\n**content to**\n**other formats**\n**via CLI**\n**interface**\n<size:10>FE_SCL_CLI_WRITE</size>" as FE_SCL_CLI_WRITE [[../tools/sphinx-codelinks/features.html#FE_SCL_CLI_WRITE]] #Gold{
'child needs:
rectangle "<size:12>Error</size>\n**Exporting**\n**marked content**\n**fails**\n<size:10>ERR_SCL_CLI_WRITE_1</size>" as ERR_SCL_CLI_WRITE_1 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_WRITE_1]] #Pink
rectangle "<size:12>Error</size>\n**Sphinx-**\n**codelinks**\n**exports wrong**\n**content**\n<size:10>ERR_SCL_CLI_WRITE_2</size>" as ERR_SCL_CLI_WRITE_2 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_WRITE_2]] #Pink
rectangle "<size:12>Error</size>\n**Exported**\n**content is**\n**malformed**\n<size:10>ERR_SCL_CLI_WRITE_3</size>" as ERR_SCL_CLI_WRITE_3 [[../tools/sphinx-codelinks/features.html#ERR_SCL_CLI_WRITE_3]] #Pink
}
node "<size:12>Tool</size>\n**Sphinx-**\n**CodeLinks**\n<size:10>TOOL_SCL</size>" as TOOL_SCL [[../tools/sphinx-codelinks/index.html#TOOL_SCL]] #0fbcf9

' Connection definition

FE_SCL_DEF -[#333333]-> TOOL_SCL
FE_SCL_C -[#333333]-> TOOL_SCL
FE_SCL_CPP -[#333333]-> TOOL_SCL
FE_SCL_PY -[#333333]-> TOOL_SCL
FE_SCL_CMT -[#333333]-> TOOL_SCL
FE_SCL_LNK -[#333333]-> TOOL_SCL
FE_SCL_RST_EXTRACTION -[#333333]-> TOOL_SCL
FE_SCL_CLI_ANALYZE -[#333333]-> TOOL_SCL
FE_SCL_CLI_DISCOVER -[#333333]-> TOOL_SCL
FE_SCL_CLI_WRITE -[#333333]-> TOOL_SCL

@enduml

ID	Title	Type
ART_SCL_NEEDS_JSON	Sphinx-CodeLinks needs.json file	artifact
ERR_SCL_1	Traceability objects are not detected in supported languages	error
ERR_SCL_2	Sphinx-codelinks halucinates traceability objects	error
ERR_SCL_C_1	Traceability objects are not detected in C language	error
ERR_SCL_C_2	Sphinx-codelinks halucinates traceability objects in C	error
ERR_SCL_CLI_ANALYZE_1	CLI integration fails silently	error
ERR_SCL_CLI_ANALYZE_2	Sphinx-codelinks halucinates marked content	error
ERR_SCL_CLI_ANALYZE_3	Sphinx-codelinks misses marked content	error
ERR_SCL_CLI_DISCOVER_1	Specifying a root directory fails	error
ERR_SCL_CLI_DISCOVER_2	Sphinx-codelinks discovers files outside the specified root directory	error
ERR_SCL_CLI_WRITE_1	Exporting marked content fails	error
ERR_SCL_CLI_WRITE_2	Sphinx-codelinks exports wrong content	error
ERR_SCL_CLI_WRITE_3	Exported content is malformed	error
ERR_SCL_CMT	Customized comment styles are not detected in supported languages	error
ERR_SCL_CPP_1	Traceability objects are not detected in C++ language	error
ERR_SCL_CPP_2	Sphinx-codelinks halucinates traceability objects in C++	error
ERR_SCL_LNK_1	Linking code to existing need items fails	error
ERR_SCL_LNK_2	Sphinx-codelinks links code to wrong need items	error
ERR_SCL_PY_1	Traceability objects are not detected in Python language	error
ERR_SCL_PY_2	Sphinx-codelinks halucinates traceability objects in Python	error
ERR_SCL_RST_EXTRACTION_1	Extracting reStructuredText from comments fails	error
ERR_SCL_RST_EXTRACTION_2	Sphinx-codelinks extracts wrong reStructuredText blocks	error
ERR_SCL_RST_EXTRACTION_3	Extracted reStructuredText blocks are malformed	error
FE_SCL_C	C Language Support	feature
FE_SCL_CLI_ANALYZE	Analyze marked content via CLI interface	feature
FE_SCL_CLI_DISCOVER	Discover the filepaths a specified root directory via CLI interface	feature
FE_SCL_CLI_WRITE	Export marked content to other formats via CLI interface	feature
FE_SCL_CMT	Customized comment styles	feature
FE_SCL_CPP	C++ Language Support	feature
FE_SCL_DEF	Define new traceability objects in source code	feature
FE_SCL_LNK	Link code to existing need items	feature
FE_SCL_PY	Python Language Support	feature
FE_SCL_RST_EXTRACTION	Extract blocks of reStructuredText embedded within comments	feature
TOOL_SCL	Sphinx-CodeLinks	tool