Added support to write the text before the first header to 0.md (d2aba895) · Commits · Centre for Testing and Interoperability / Markdown specifications development / Specification tools

toMkdocs/toMkdocs.py

+63 −8

Original line number	Diff line number	Diff line
		@@ -37,10 +37,52 @@ class Line:
		@dataclass
		class Clause:
		""" Represents a clause in the markdown file. """
		level:int
		clauseNumber:str
		title:str
		lines:list[Line]
		_level:int
		_clauseNumber:str
		_title:str
		_lines:list[Line]


		@property
		def level(self) -> int:
		""" Return the level of the clause. """
		return self._level


		@property
		def clauseNumber(self) -> str:
		""" Return the clause number. """
		return self._clauseNumber if self._clauseNumber else '0'


		@clauseNumber.setter
		def clauseNumber(self, value:str) -> None:
		""" Set the clause number. """
		self._clauseNumber = value


		@property
		def title(self) -> str:
		""" Return the title of the clause. """
		return self._title


		@title.setter
		def title(self, value:str) -> None:
		""" Set the title of the clause. """
		self._title = value


		@property
		def lines(self) -> list[Line]:
		""" Return the lines of the clause. """
		return self._lines


		@lines.setter
		def lines(self, value:list[Line]) -> None:
		""" Set the lines of the clause. """
		self._lines = value


		@property
		@@ -190,7 +232,7 @@ def analyseMarkdown(filename:str) -> list[Clause]:
		def splitMarkdownDocument(clauses:list[Clause],
		ignoreTitles:list[str] = [],
		splitLevel:int = 1,
		ignoreUntilFirstHeading:bool = True) -> list[Clause]:
		includeUntilFirstHeading:bool = False) -> list[Clause]:
		""" Split the clauses at a certain level. This is used to create the separate
		markdown files for MkDocs.

		@@ -198,7 +240,7 @@ def splitMarkdownDocument(clauses:list[Clause],
		clauses: The list of clauses.
		ignoreTitles: A list of titles that should be ignored. They are not included in the output.
		splitLevel: The level at which the clauses should be split.
		ignoreUntilFirstHeader: Ignore all clauses until the first heading.
		includeUntilFirstHeader: Ignore all clauses until the first heading.

		Returns:
		The list of clauses.
		@@ -221,7 +263,7 @@ def splitMarkdownDocument(clauses:list[Clause],
		outClauses[-1].extend(clause)

		# Remove the first clause if it has no title
		if ignoreUntilFirstHeading:
		if not includeUntilFirstHeading:
		while len(outClauses[0].title) == 0:
		outClauses.pop(0)

		@@ -391,6 +433,15 @@ def writeClauses(outClauses:list[Clause], filename:str, navTitle:str) -> None:
		file.write(f' - {navTitle}:\n')
		for i, f in enumerate(outClauses):

		# TODO generate also the navigation for the first non-header clause
		# if not f.title:
		# if i == 0:
		# file.write(f"{' '*(f.level+1)}- '': '{f.clauseNumber}.md'\n")
		# continue
		if not f.title:
		continue


		# TODO handle if the next clause is more than one level deeper

		_title = f.title.replace("'", '"')
		@@ -431,7 +482,9 @@ def processDocument(args:argparse.Namespace) -> None:

		# Analyse the markdown file
		clauses = analyseMarkdown(document)
		clauses = splitMarkdownDocument(clauses, [ t.casefold() for t in args.ignore_clause ], args.split_level)
		clauses = splitMarkdownDocument(clauses,
		[ t.casefold() for t in args.ignore_clause ],
		args.split_level,args.include_title)
		clauses = updateLinks(clauses)
		clauses = updateNotes(clauses)
		clauses = prepareForMkdocs(clauses)
		@@ -450,9 +503,11 @@ if __name__ == '__main__':
		parser.add_argument('--verbose', '-v', action = 'store_true', help = 'verbose output during processing')
		parser.add_argument('--very-verbose', '-vv', action = 'store_true', help = 'very verbose output during processing')
		parser.add_argument('--ignore-clause', '-ic', metavar = 'clause', nargs = '+', default = [ 'Contents', 'History' ], help = 'ignore headers in the markdown document')
		parser.add_argument('--include-title', '-it', action = 'store_true', help = 'include the content before the first heading in the output files as "0.md"')
		parser.add_argument('--split-level', '-sl', metavar = 'level', type = int, default = 2, help = 'on which level to split clauses to separate files')
		parser.add_argument('--media-directory', '-md', metavar = 'media-directory', default = 'media', help = 'directory name where media files are stored')
		parser.add_argument('--title', '-t', metavar = 'title', required = True, help = 'mkdocs navigation tile')

		parser.add_argument('document', type = str, help = 'a oneM2M markdown specification document to process')
		args = parser.parse_args()
		processDocument(args)