Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restore possibility to use anchors #12

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Restore possibility to use anchors #12

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca27394
Restore possibility to use anchors
tvdijen Dec 18, 2024
dd07dda
Fix indentation + remove lots of excess whitespace
tvdijen Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 50 additions & 46 deletions mk_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,26 +18,30 @@
# - add header, navigation and footer to the converted file
def md2html(md_file, html_file, file_name):
print("Transforming " + md_file + " into " + html_file)

with open(md_file, 'r') as f:
text = f.read()

html = pymd.convert(text)
soup = BeautifulSoup(html, 'html.parser')
for a in soup.findAll('a'):

if not a['href'].startswith(('http://', 'https://', '#')):
if not a['href'].endswith(('html')):
a['href'] = a['href']+".html"

parts = a['href'].split('#')
if not parts[0].endswith(('html')):
a['href'] = parts[0]+".html"

if (len(parts) > 1):
a['href'] = a['href'] + '#' + parts[1]

if (str(a['href']).find(":") > 0):
a['href'] = a['href'].replace(":", "/")

# TODO: At this point we could use title and description to auto generate a breadcrum or an index
#title = soup.find('h1').string
#if (len(title.split(":")) > 1):
# title = title.split(":")[1]

#desc = ""
#p = soup.find('p')
#if not p is None:
Expand All @@ -48,7 +52,7 @@ def md2html(md_file, html_file, file_name):

# search a filesystem directory for subdirs and retum these in a list
def getsubdirs(dir_path):
return(glob.glob(dir_path + '*/'))
return(glob.glob(dir_path + '*/'))

# search a filesystem directory for markdown (md) files and parse these into html using the md2html function
def parsefiles(docsdir, outputdir):
Expand All @@ -71,38 +75,38 @@ def parsefiles(docsdir, outputdir):
# filter out the ones that do not have a ssp module
def getmodulerepos():
module_repos = []

with urllib.request.urlopen("https://api.github.com/users/simplesamlphp/repos?per_page=100") as url:
repos = json.loads(url.read().decode())

for repo in repos:
a_repo = {"name": [], "description": [], "html_url": [], "short_name": []}
# we assume all module will have a name that starts with 'simplesamlphp-module-'

# we assume all module will have a name that starts with 'simplesamlphp-module-'
if (repo['name'].find('simplesamlphp-module-') == 0 and not repo['archived']):
a_repo['name'] = str(repo['name'])
a_repo['description'] = str(repo['description'])
a_repo['html_url'] = str(repo['html_url'])
a_repo['short_name'] = a_repo['name'].split("-")[2]

module_repos.append(a_repo)
module_repos.append(a_repo)

return module_repos

# clone a specific git repo to a given directory. Optionally fetch specific version
# Target directories will be autocreated
def getgitrepo(repo, repo_clone_dir, repo_root, version=None):
os.makedirs(os.path.join(repo_clone_dir))
os.chdir(repo_clone_dir)

if (version is None or version == 'devel'):
os.system('git clone --depth=1 ' + repo)
else:
os.system('git clone --depth=1 --branch simplesamlphp-' + version + ' ' + repo)
os.chdir(repo_clone_dir + repo_root)

print("Working in git repo from" + os.getcwd())

os.system('git status')

# make the header and headerbad div contents for indjection into each documentation page
Expand Down Expand Up @@ -137,14 +141,14 @@ def mkContentHeader(versions):
content += '</nav>'
content += '<div id="content">'
content += '</header>'
s = BeautifulSoup(content, 'html.parser')

s = BeautifulSoup(content, 'html.parser')

return s.prettify()

# make a navigation structure based on the versions we have doucmentation for
# make a navigation structure based on the versions we have doucmentation for
def mkNavigation(versions):

#content = '<div id="langbar" style="clar: both"><div id="navigation">Documentation is available for the following versions: '
#for version in versions:
# content += '<a href="/docs/'+version+'/index.html">'+version+'</a> | '
Expand All @@ -155,24 +159,24 @@ def mkNavigation(versions):
if version == 'devel':
content += '<div class="menuitem first">'
else:
content += '<div class="menuitem">'
content += '<div class="menuitem">'

content += '<a href="'+site_base_path+version+'/index.html">'+version
if version == versions[0]:
content += ' (stable)'
content += '</a></div>'

content += ' <div class="menuitem last">'
content += ' <a href="' + site_base_path + 'contributed_modules.html"> Contributed modules</a>'
content += ' </div>'

content += '</div>'

return content

# make sure some resources are put in the right place for the website
def mkResources(root_dir, web_root):
# starter index.html (just a redirect to 'stable')
# starter index.html (just a redirect to 'stable')
os.system('cp ' + root_dir + 'resources/index.html ' + web_root + 'index.html ')

# Builds an index.md file of all the contributed repository documetation (if available)
Expand All @@ -181,20 +185,20 @@ def mkcontribmodsindex(contrib_mods, module_index_file, contrib_mods_files):
module_index += "===========================\n\n"

pages = {}

for page in contrib_mods_files:
s = page.split("/")
mod_name = s[len(s) -2]
page_name = s[len(s) -1]

if mod_name not in pages.keys():
pages[mod_name] = []

pages[mod_name].append(page_name)

for module in contrib_mods:
module_index += " * "+ module["name"] + "\n"

if module["description"] is not None:
module_index += ": " + module["description"] + "\n"

Expand All @@ -204,30 +208,30 @@ def mkcontribmodsindex(contrib_mods, module_index_file, contrib_mods_files):
for page in pages[module["short_name"]]:
module_index += " * Documentation: ["+ page + "](contrib_modules/"+ module["short_name"] + "/" + page +")\n"
except KeyError:
# some modules do not have documentation, just ignore them
# some modules do not have documentation, just ignore them
pass

with open(module_index_file, 'w+') as f:
f.write(module_index)

# reads files and (sub)dirs from a given directory
def getListOfFiles(dirName):
# create a list of file and sub directories
# names in the given directory
# create a list of file and sub directories
# names in the given directory
listOfFile = os.listdir(dirName)
allFiles = list()
# Iterate over all the entries
for entry in listOfFile:
# Create full path
fullPath = os.path.join(dirName, entry)
# If entry is a directory then get the list of files in this directory
# If entry is a directory then get the list of files in this directory
if os.path.isdir(fullPath):
allFiles = allFiles + getListOfFiles(fullPath)
else:
allFiles.append(fullPath)

return allFiles

################################################
#
# MAIN
Expand Down Expand Up @@ -276,7 +280,7 @@ def getListOfFiles(dirName):
for ssp_version in ssp_versions:
print("Working on: " + ssp_version)
#print("Repo Root: " + repo_root_dir)

version_dir = tempdir + ssp_version + "/"
#print("Version dir: " + version_dir)
getgitrepo('https://github.com/simplesamlphp/simplesamlphp.git', version_dir, repo_root_dir, ssp_version)
Expand Down Expand Up @@ -306,22 +310,22 @@ def getListOfFiles(dirName):
print("Working on: " + module["name"])
contrib_mod_dir = tempdir + "contrib_modules/" + module["name"] + "/"
contrib_mod_web_dir = site_root_dir + "contrib_modules" + "/"
# We assume contributes modules live in the ssp repo and are named 'simplesamlphp-module-*'

# We assume contributes modules live in the ssp repo and are named 'simplesamlphp-module-*'
getgitrepo(module["html_url"], contrib_mod_dir, module["name"])

module_dir = os.path.join(contrib_mod_dir, module["name"], "docs/")
print(module_dir)

if os.path.isdir(module_dir):
module_output_dir = os.path.join(contrib_mod_web_dir, module["short_name"]+ "/")
parsefiles(module_dir, module_output_dir)

else:
print("No docs found for '" + module["name"] +"'")

# Now build an index of generated documents
contrib_mods_files= getListOfFiles(site_root_dir + "contrib_modules" + "/")
contrib_mods_files= getListOfFiles(site_root_dir + "contrib_modules" + "/")
mkcontribmodsindex(contrib_mods, module_index_file, contrib_mods_files)
md2html(module_index_file, site_root_dir + 'contributed_modules.html', 'contributed_modules.html')

Expand Down
Loading