mirror of
https://github.com/carp-lang/Carp.git
synced 2024-09-11 05:25:28 +03:00
e9537a8ba9
* docs: implemented python script to convert local documentation from .md files to .html files * docs: filled index.md; reviewed all references in .md files * docs: updated Embedded.md and resized carp_on_arduboy.jpg to sensible width * docs: copy sub folders (./docs/core and ./docs/sdl) to ./docs-html/ and refer docu to it * docs: phrased requirements more clearly * docs: generate docs for Standard libraries before converting .md docs to .html * docs: change index to markdown lists * docs: index.md worked around limitation in md converter * docs: removed modules count from Libraries.md Co-authored-by: guberatsie <gunnar.bernhardt@siemens.com>
98 lines
3.6 KiB
Python
Executable File
98 lines
3.6 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
|
|
# If you want to browse the Carp documentation offline with all the bells and whistles
|
|
# (e.g. working hyperlinks to other documents and embedded graphics) that are usually
|
|
# provided by the github webpage, you can convert it to static html with this script.
|
|
#
|
|
# It needs Python3 and the markdown module to work. Install the latter with:
|
|
# sudo pip install markdown
|
|
# or depending on you system configuration (e.g. on Windows):
|
|
# pip install markdown
|
|
#
|
|
# Start the conversion with:
|
|
# python3 zConvertMd2Html.py
|
|
# or depending on you system configuration (e.g. on Windows):
|
|
# python zConvertMd2Html.py
|
|
# or by executing the script itself (only on *NIX / BSD):
|
|
# chmod u+x zConvertMd2Html.py
|
|
# ./zConvertMd2Html.py
|
|
#
|
|
# Please note:
|
|
# inter-document references do not work since the markdown-library does not create
|
|
# the required html-anchor elements for headings. :-/
|
|
|
|
import markdown, glob, os, platform, re, shutil
|
|
|
|
# some definitions
|
|
pat = re.compile("\[(.*?)\]\((.*?)\)")
|
|
docPath = "../docs/"
|
|
docPathLen = len(docPath)
|
|
|
|
def change_md2html( match ):
|
|
# unfortunately we can not use filters inside the regular expression like this:
|
|
# pat = re.compile("\[(.*?)\]\(((?!http).*?)\.md(#.*?)?\)")
|
|
# ... because that would create false matches for cases like this:
|
|
# [desc1](ref1) txt1 (desc2(ref2). txt2 [desc3](https://url1/doc1#anchor1)
|
|
# since the match is still too greedy.
|
|
mgroups = match.groups()
|
|
refParts = mgroups[1].split("#")
|
|
refFile = refParts[0]
|
|
lFile = refFile.lower()
|
|
if len(refParts) < 2:
|
|
refAnchor = ""
|
|
else:
|
|
refAnchor = "#" + refParts[1]
|
|
if lFile.startswith("http") or not lFile.endswith(".md") or lFile.startswith("../"):
|
|
# not a reference to a local .md file => return unchanged match
|
|
mSpan = match.span()
|
|
new = match.string[ mSpan[0]: mSpan[1] ]
|
|
print("\tkept reference: " + new)
|
|
else:
|
|
new = "[%s](%s.html%s)" % (mgroups[0], refFile[:-3], refAnchor )
|
|
print("\tadjusted reference: " + new)
|
|
return new
|
|
|
|
def generate(fnInput, fnBase4Output):
|
|
if not os.path.isfile(fnInput):
|
|
print( "copying directory: %s to %s" % (fnInput,fnBase4Output) )
|
|
shutil.copytree( fnInput, fnBase4Output)
|
|
elif fnInput.endswith(".md"):
|
|
print( "converting to html: " + fnInput)
|
|
# replace any link "[desc](ref.md)" with "[desc](ref.html" if ref does not start with "http" since we only want to change locally available documentation
|
|
with open(fnInput) as finput:
|
|
content = finput.read()
|
|
new_content = re.sub(pat, change_md2html, content)
|
|
with open( fnBase4Output[:-3] + '.html', 'w') as foutput:
|
|
foutput.write( markdown.markdown( new_content, extensions=['fenced_code', 'codehilite'] ) )
|
|
else:
|
|
# any other files might be resources (e.g. pictures) which probably need to be copied
|
|
print( "copying file: %s to %s" % (fnInput,fnBase4Output) )
|
|
shutil.copy( fnInput, fnBase4Output)
|
|
|
|
def remove_existing_dir(path):
|
|
if os.path.exists(path):
|
|
shutil.rmtree(path)
|
|
|
|
|
|
# main program
|
|
|
|
print("(re)generating html docs for Carp standard library...")
|
|
pOld = os.getcwd()
|
|
os.chdir("..")
|
|
cmd = "carp -x ./docs/core/generate_core_docs.carp"
|
|
if platform.system()=="Windows":
|
|
cmd = cmd.replace("/","\\")
|
|
os.system(cmd)
|
|
os.chdir(pOld)
|
|
print("... done\n")
|
|
|
|
for p in glob.glob("./*/"):
|
|
remove_existing_dir(p)
|
|
|
|
# generate html files
|
|
for fname in glob.glob(docPath+"*"):
|
|
generate( fname, fname[docPathLen:] )
|
|
generate( "./core/README.md", "./core/README.md" )
|
|
|
|
print("\ndone :-)")
|