FilesExpand file tree

main

/

default.parser-config.yml

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

226 lines (218 loc) · 7.65 KB

main

/

default.parser-config.yml

Copy path

Top

File metadata and controls

• Code
• Blame

226 lines (218 loc) · 7.65 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

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

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

version: 1

project:

name: doc2me

repository: Doc2Me/Parser/ # GitHub owner/repo slug (e.g. "owner/repo")

default_branch: main

# Define the sources for the parser.

# Possible sources: code, tests, docblocks, pull_requests, issues, issue_comments, pull_request_comments.

#

# Common parameters per source:

# - enabled (bool): true|false

# - include (sequence): inclusion filters

# - exclude (sequence): exclusion filters

#

# Filter item shapes:

# 1) Plain string

# - For code/tests/docblocks: treated as a path/glob filter.

# - For tracker sources: treated as a source-native filter value.

# 2) Typed rule object

# - type (string): filter kind

# - value (string|sequence<string>): one or more filter values

#

# Allowed typed rule kinds by source:

# - code, tests: path

# - docblocks: tag, path

# - pull_requests, issues, issue_comments, pull_request_comments: author, state, label

#

# Examples:

# - code.exclude:

# - "**/vendor/**"

# - type: path

# value: "packages/legacy/**"

# - docblocks.include:

# - type: tag

# value: ["@public", "@api"]

# - pull_requests.exclude:

# - type: author

# value: "dependabot"

# - type: state

# value: "open"

# - issues.exclude:

# - type: label

# value: ["wontfix", "duplicate"]

sources:

code:

enabled: true

include:

- "packages/**"

exclude:

- "**/node_modules/**"

- "**/vendor/**"

tests:

enabled: true

include:

- "packages/**/test/**"

docblocks:

enabled: true

include:

- type: "tag"

value: ["@public", "@api", "@internal"]

pull_requests:

enabled: true

exclude:

- type: author

value: dependabot

- type: state

value: open

issues:

enabled: true

exclude:

- type: state

value: open

include:

- type: tag

value: ["needs-docs", "todo" ]

issue_comments:

enabled: false

pull_request_comments:

enabled: false

# Define the docs types to generate. Each doc type can specify:

# - enabled (bool): true|false

# - audience (string): target audience for the doc type (e.g., developer, user)

# - evidence_policy: rules for which evidence sources are mandatory, preferred, or ignored for claims in this doc type

# - require: mandatory sources; claims/doc output are invalid without them

# - prefer: higher-priority sources when multiple valid sources exist; not mandatory

# - ignore: sources that must not be used for this doc type

#

# Possible extensions for the future:

# - `evidence_policy` params with `evidence_overrides` per `doc_type`.

# - `output_format` to specify the desired output format for each doc type (e.g., markdown, html, pdf).

# - `template` to specify a custom template for rendering each doc type, allowing for different layouts or styles based on the audience or content type.

#

# Example:

# api_reference:

# output:

# format: markdown

# template: api_reference

doc_types:

api_reference:

enabled: true

audience: developer

evidence_policy:

require:

- code

- docblocks

ignore:

- pull_requests

changelog:

enabled: true

audience: developer

evidence_policy:

require:

- code

prefer:

- pull_requests

user_guide:

enabled: true

audience: end-user

evidence_policy:

require:

- code

prefer:

- docblocks

dev_note:

enabled: true

evidence_policy:

require:

- code

- pull_requests

field_guide:

enabled: true

evidence_policy:

require:

- code

- docblocks

# Define the evidence requirements and policies for claims made in the generated docs.

# This section can specify:

# - minimum_sources: the minimum number of independent sources required to support a claim

# - freshness: rules about how old evidence can be to be considered valid (e.g., max age in days for issues or PRs)

evidence:

minimum_sources: 2

freshness:

max_issue_age_days: 90

max_pr_age_days: 180

# Define inference rules and settings for generating content that is not explicitly stated in the sources but can be reasonably inferred.

# This section can specify:

# - mode: the inference mode (e.g., constrained_synthesis, evidence_driven, gap_filling)

# - require_label_for_inferred_content: whether inferred content must be explicitly labeled as such

# - label_for_inferred_content: the label to use for inferred content if required

# - allow_gap_filling: whether the system is allowed to generate content to fill gaps in

inference:

mode: constrained_synthesis

require_label_for_inferred_content: true

label_for_inferred_content: "[inferred]"

allow_gap_filling: false

# Define the traceability and documentation generation settings, including how to handle insufficient or conflicting evidence.

#

# - traceability: settings for generating traceability artifacts that link claims back to their supporting evidence

# - failure_behavior: rules for how to handle cases where evidence is insufficient or conflicting (e.g., fail, mark_uncertain, ignore)

# The traceability settings specify:

# - enabled: whether to generate traceability artifacts

# - include_in_final_docs: whether to include traceability information in the final generated documentation

# - artifact_format: the format for traceability artifacts (e.g., json, csv)

# The failure_behavior settings specify:

# - on_insufficient_evidence: the action to take when a claim does not have enough supporting evidence (e.g., fail, mark_uncertain, ignore)

# - on_conflicting_evidence: the action to take when there are conflicting pieces of evidence for a claim (e.g., fail, mark_uncertain, ignore)

#

# Example of a claim with supporting evidence from multiple sources, demonstrating how the system can extract and correlate information to generate a well-supported documentation claim.

#

# ## Authentication

#

# The API supports token-based authentication via bearer tokens.

#

# {

# "doc_type": "api_reference",

# "claims": [

# {

# "id": "claim.auth.bearer_tokens",

# "text": "The API supports token-based authentication via bearer tokens.",

# "status": "supported",

# "evidence": [

# {

# "source": "code",

# "location": "packages/auth/src/AuthMiddleware.php:42",

# "excerpt": "if (str_starts_with($header, 'Bearer ')) { ... }"

# },

# {

# "source": "docblocks",

# "location": "packages/auth/src/AuthMiddleware.php:10",

# "excerpt": "@description Validates Bearer tokens from Authorization header."

# }

# ]

# }

# ]

# }

outputs:

traceability:

enabled: true

include_in_final_docs: false

artifact_format: json

failure_behavior:

on_insufficient_evidence: fail

on_conflicting_evidence: mark_uncertain

# Define execution settings for the parser, including caching, debug file generation, and strict mode.

#

# - cache: whether to enable caching of intermediate results to speed up subsequent runs

# - save_debug_files: whether to save debug files with intermediate data and processing details for troubleshooting

# - strict_mode: whether to enforce strict validation of sources and evidence, causing the parser to fail if any issues are detected with the input data or evidence quality

#

# Cache

# Uses cached results so repeated runs are faster and avoid reprocessing unchanged inputs.

# Debug Files

# Writes intermediate outputs (parsed source snapshots, evidence maps, temporary generation artifacts) for debugging and auditability.

# Strict Mode

# Enforces strict validation/error handling. Missing required config, invalid evidence, or schema/rule violations fail the run instead of continuing with warnings.

execution:

cache: true

save_debug_files: true

strict_mode: true