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

Jump to bottom

HTML Doc enhancement to build docs for all API releases and sort it in proper order #181

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

HTML Doc enhancement to build docs for all API releases and sort it in proper order #181

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0196c22
Adding support for getting dot notations
pdellaert Jan 2, 2019
97d62fe
Adding support for using branch information in language generators, i…
pdellaert Jan 2, 2019
3e8e9d5
Updating with natsort
pdellaert Jun 5, 2020
88aa5c7
Fixing sort order of release so the newest release is a the top
pdellaert May 10, 2023
591db63
Updating version for new functionality
pdellaert May 10, 2023
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
15 changes: 8 additions & 7 deletions monolithe/generators/lang/html/templates/index.html.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<html lang="en">
<head>
<title>{{ product_name }} API Reference {{ apiversion }}</title>
<link rel="stylesheet" href="../css/bootstrap.css">
<link rel="stylesheet" href="../css/style.css">
<link rel="stylesheet" href="{% if branch %}../{% endif %}../css/bootstrap.css">
<link rel="stylesheet" href="{% if branch %}../{% endif %}../css/style.css">
</head>

<body data-spy="scroll" data-target="#navbarmain">
Expand All @@ -17,12 +17,11 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">{{ product_name }} API Documentation {{ apiversion }}</a>

<a class="navbar-brand" href="{% if branch %}../{% endif %}../index.html">{{ product_name }} API Documentation</a><span class="navbar-brand"> &gt; </span><span class="navbar-brand">{{ apiversion }}</span>{% if branch %}<span class="navbar-brand"> &gt; </span><span class="navbar-brand">{{ branch }}</span>{% endif %}
</div>
<div class="collapse navbar-collapse" id="navbar">
<ul class="nav navbar-nav">
<li><a href="../usage.html">API Usage</a></li>
<li><a href="{% if branch %}../{% endif %}../usage.html">API Usage</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Components <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
Expand All @@ -38,12 +37,14 @@
</ul>
</li>
</ul>
<!--
<form class="navbar-form navbar-right" role="search">
<div class="form-group dropdown">
<input type="text" class="form-control" placeholder="Search" id="searchfield">
<ul class="dropdown-menu dropdown-menu-left" role="menu" id="searchresult" style="display: none"></ul>
</div>
</form>
-->
</div>
</div>
</nav>
Expand Down Expand Up @@ -85,8 +86,8 @@
</div>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<script src="../js/bootstrap.min.js"></script>
<script src="../js/search.js"></script>
<script src="{% if branch %}../{% endif %}../js/bootstrap.min.js"></script>
<script src="{% if branch %}../{% endif %}../js/search.js"></script>

<script>
$(document).ready(function() {
Expand Down
10 changes: 9 additions & 1 deletion monolithe/generators/lang/html/templates/main_index.html.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,18 @@

<div class="container" id="content">
<h1>Available Versions</h1>
{% for version, path in apiversion.iteritems() %}
{% for version in version_keys %}
{% set path = apiversions[version] %}
<div class="row bordered-row">
<div class="col-xs-12">
<a href="{{ path }}/index.html" title="{{ product_name}} API version {{ version }}">{{ product_name}} API version {{ version }}</a>
{% if version in version_releases.keys() %}
<ul>
{% for release in version_releases[version] %}
<li><a href="{{ path }}/{{ release }}/index.html" title="{{ product_name }} API version {{ version }} - {{ release }}">{{ release }}</a>
{% endfor %}
</ul>
{% endif %}
</div>
</div>
{% endfor %}
Expand Down
12 changes: 7 additions & 5 deletions monolithe/generators/lang/html/templates/object.html.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<html lang="en">
<head>
<title>{{ specification.entity_name }} API Reference {{ apiversion }}</title>
<link rel="stylesheet" href="../css/bootstrap.css">
<link rel="stylesheet" href="../css/style.css">
<link rel="stylesheet" href="{% if branch %}../{% endif %}../css/bootstrap.css">
<link rel="stylesheet" href="{% if branch %}../{% endif %}../css/style.css">
</head>

<body data-spy="scroll" data-target="#navbarmain">
Expand All @@ -17,7 +17,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">{{ product_name }} API Documentation {{ apiversion }}</a>
<a class="navbar-brand" href="{% if branch %}../{% endif %}../index.html">{{ product_name }} API Documentation</a><span class="navbar-brand"> &gt; </span><a class="navbar-brand" href="index.html">{{ apiversion }}</a>{% if branch %}<span class="navbar-brand"> &gt; </span><a class="navbar-brand" href="index.html">{{ branch }}</a>{% endif %}
</div>
<div class="collapse navbar-collapse" id="navbar">
<ul class="nav navbar-nav">
Expand All @@ -36,12 +36,14 @@
</ul>
</li>
</ul>
<!--
<form class="navbar-form navbar-right" role="search">
<div class="form-group dropdown">
<input type="text" class="form-control" placeholder="Search" id="searchfield">
<ul class="dropdown-menu dropdown-menu-left" role="menu" id="searchresult" style="display: none"></ul>
</div>
</form>
-->
</div>
</div>
</nav>
Expand Down Expand Up @@ -264,8 +266,8 @@
</div>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<script src="../js/bootstrap.min.js"></script>
<script src="../js/search.js"></script>
<script src="{% if branch %}../{% endif %}../js/bootstrap.min.js"></script>
<script src="{% if branch %}../{% endif %}../js/search.js"></script>
<script>
$(document).ready(function()
{
Expand Down
63 changes: 44 additions & 19 deletions monolithe/generators/lang/html/writers/apiversionwriter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

from monolithe.generators.lib import TemplateFileWriter
from monolithe.lib import SDKUtils, TaskManager
from monolithe.lib import SDKUtils, TaskManager, Printer


class APIVersionWriter(TemplateFileWriter):
Expand Down Expand Up @@ -63,18 +63,20 @@ def _get_actions(self, obj):
actions.append("DELETE")
return actions

def perform(self, specifications):
def perform(self, specifications, branch, latest):
"""
"""

if branch:
branch = SDKUtils.get_dot_notation(branch)
Printer.log("Writing HTML docs for version %s, release %s. Generating latest: %s" % (self._api_version, branch, latest))
task_manager = TaskManager()
for rest_name, specification in specifications.items():
task_manager.start_task(method=self._write_specification, specification=specification, specification_set=specifications)
task_manager.start_task(method=self._write_specification, specification=specification, specification_set=specifications, branch=branch, latest=latest)
task_manager.wait_until_exit()

self._write_index(specifications)
self._write_index(specifications=specifications, branch=branch, latest=latest)

def _write_specification(self, specification, specification_set):
def _write_specification(self, specification, specification_set, branch=None, latest=True):
"""
"""
if specification.rest_name:
Expand All @@ -100,21 +102,44 @@ def _write_specification(self, specification, specification_set):

self_apis = [{"actions": self._get_actions(specification)}]

self.write(destination=self.output_directory, filename=filename, template_name="object.html.tpl",
apiversion=self._api_version,
specification=specification,
parent_apis=parent_apis,
child_apis=child_apis,
member_apis=member_apis,
self_apis=self_apis,
product_name=self._product_name)
if branch:
self.write(destination="%s/%s" % (self.output_directory, branch), filename=filename, template_name="object.html.tpl",
apiversion=self._api_version,
specification=specification,
parent_apis=parent_apis,
child_apis=child_apis,
member_apis=member_apis,
self_apis=self_apis,
product_name=self._product_name,
branch=branch)
if latest:
# Also write to the main folder
self.write(destination=self.output_directory, filename=filename, template_name="object.html.tpl",
apiversion=self._api_version,
specification=specification,
parent_apis=parent_apis,
child_apis=child_apis,
member_apis=member_apis,
self_apis=self_apis,
product_name=self._product_name,
branch=None)

return (filename, specification.entity_name)

def _write_index(self, specifications):
def _write_index(self, specifications, branch=None, latest=True):
"""
"""
self.write(destination=self.output_directory, filename="index.html", template_name="index.html.tpl",
apiversion=self._api_version,
specifications=list(specifications.values()),
product_name=self._product_name)
specifications = sorted(specifications.values(), key=lambda k: k.resource_name)
if branch:
self.write(destination="%s/%s" % (self.output_directory, branch), filename="index.html", template_name="index.html.tpl",
apiversion=self._api_version,
specifications=specifications,
product_name=self._product_name,
branch=branch)
if latest:
# Also write to the main folder
self.write(destination=self.output_directory, filename="index.html", template_name="index.html.tpl",
apiversion=self._api_version,
specifications=specifications,
product_name=self._product_name,
branch=None)
19 changes: 14 additions & 5 deletions monolithe/generators/lang/html/writers/packagewriter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@

from monolithe.generators.lib import TemplateFileWriter
from monolithe.lib import SDKUtils
from natsort import natsorted


class PackageWriter(TemplateFileWriter):
Expand All @@ -45,19 +46,27 @@ def __init__(self, monolithe_config):

self.output_directory = "%s/html/" % (self._output)

def perform(self, apiversions):
def perform(self, apiversions, branches):
"""
"""
self._write_main_index(apiversions=apiversions)
self._write_main_index(apiversions=apiversions, branches=branches)

def _write_main_index(self, apiversions):
def _write_main_index(self, apiversions, branches):
"""
"""
versions = {}
version_releases = {}

for v in apiversions:
versions[v] = SDKUtils.get_string_version(v)
tmp_releases = []
if v in branches.keys():
for b in branches[v]:
tmp_releases.append(SDKUtils.get_dot_notation(b))
version_releases[v] = natsorted(tmp_releases, reverse=True)

self.write(destination=self.output_directory, filename="index.html", template_name="main_index.html.tpl",
apiversion=versions,
product_name=self._product_name)
version_keys=natsorted(versions.keys(), reverse=True),
apiversions=versions,
product_name=self._product_name,
version_releases=version_releases)
6 changes: 3 additions & 3 deletions monolithe/generators/lib/generator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,19 +52,19 @@ def run(self, branches=None):
for branch in branches:
Printer.log("Switching to branch %s" % branch)
self.directory_manager.switch_branch(branch)
specification_info.append(self.get_specifications_infos_from_folder())
specification_info.append(self.get_specifications_infos_from_folder(branch=branch))
else:
specification_info.append(self.get_specifications_infos_from_folder())

self.generate(specification_info=specification_info)

def get_specifications_infos_from_folder(self):
def get_specifications_infos_from_folder(self, branch=None):
Printer.log("retrieving specifications from folder \"%s\"" % (self.directory_manager.folder))
api_info = self.directory_manager.get_api_info()
specifications = self.directory_manager.get_all_specifications()
self._resolve_parent_apis(specifications)
Printer.log("%d specifications retrieved from folder \"%s\" (api version: %s)" % (len(specifications), self.directory_manager.folder, api_info["version"]))
return {"specifications": specifications, "api": api_info}
return {"specifications": specifications, "api": api_info, "branch": branch}

def generate(self, specification_info):
raise NotImplementedError()
Expand Down
9 changes: 7 additions & 2 deletions monolithe/generators/managers/apiversionmanager.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

import inspect
from .manager import Manager


Expand All @@ -37,10 +38,14 @@ def __init__(self, monolithe_config):
"""
super(APIVersionManager, self).__init__(monolithe_config=monolithe_config, target_name='APIVersionWriter')

def execute(self, specifications, api_info):
def execute(self, specifications, api_info, branch, latest):
"""
"""
klass = self.get_managed_class()
if klass:
writer = klass(monolithe_config=self.monolithe_config, api_info=api_info)
writer.perform(specifications=specifications)
writer_perform_spec = inspect.getargspec(writer.perform)
if 'branch' in writer_perform_spec.args and 'latest' in writer_perform_spec.args:
writer.perform(specifications=specifications, branch=branch, latest=latest)
else:
writer.perform(specifications=specifications)
9 changes: 7 additions & 2 deletions monolithe/generators/managers/mainmanager.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

import inspect
from .manager import Manager


Expand All @@ -37,10 +38,14 @@ def __init__(self, monolithe_config):
"""
super(MainManager, self).__init__(monolithe_config=monolithe_config, target_name='PackageWriter')

def execute(self, apiversions):
def execute(self, apiversions, branches=None):
"""
"""
klass = self.get_managed_class()
if klass:
writer = klass(monolithe_config=self.monolithe_config)
writer.perform(apiversions=apiversions)
writer_perform_spec = inspect.getargspec(writer.perform)
if 'branches' in writer_perform_spec.args:
writer.perform(apiversions=apiversions, branches=branches)
else:
writer.perform(apiversions=apiversions)
11 changes: 9 additions & 2 deletions monolithe/generators/sdkapiversiongenerator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
from builtins import object

from monolithe.generators.managers import APIVersionManager, DocumentationManager
from natsort import natsorted


class SDKAPIVersionGenerator(object):
Expand All @@ -44,8 +45,14 @@ def __init__(self, monolithe_config):
def generate(self, specification_info):
"""
"""
for info in specification_info:
specification_info = natsorted(specification_info, key=lambda k: k["branch"])
specification_info = natsorted(specification_info, key=lambda k: k["api"]["version"])
spec_max_index = len(specification_info) - 1
for index, info in enumerate(specification_info):
latest = False
if index == spec_max_index or (index < spec_max_index and info["api"]["version"] != specification_info[index+1]["api"]["version"]):
latest = True
manager = APIVersionManager(monolithe_config=self.monolithe_config)
manager.execute(specifications=info["specifications"], api_info=info["api"])
manager.execute(specifications=info["specifications"], api_info=info["api"], branch=info["branch"], latest=latest)
doc_manager = DocumentationManager(monolithe_config=self.monolithe_config)
doc_manager.execute(info["specifications"], info["api"])
12 changes: 10 additions & 2 deletions monolithe/generators/sdkgenerator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,16 +70,24 @@ def generate(self, specification_info):

version_generator = SDKAPIVersionGenerator(self.config)
apiversions = []
branches = {}

for info in specification_info:
Printer.log("transforming specifications into %s for version %s..." % (lang, info["api"]["version"]))
if "branch" in info.keys() and info["branch"]:
Printer.log("transforming specifications into %s for version %s, branch %s..." % (lang, info["api"]["version"], info["branch"]))
else:
Printer.log("transforming specifications into %s for version %s..." % (lang, info["api"]["version"]))
apiversions.append(info["api"]["version"])
if "branch" in info.keys() and info["branch"]:
if info["api"]["version"] not in branches.keys():
branches[info["api"]["version"]] = []
branches[info["api"]["version"]].append(info["branch"])

version_generator.generate(specification_info=specification_info)

Printer.log("assembling...")
manager = MainManager(monolithe_config=self.config)
manager.execute(apiversions=apiversions)
manager.execute(apiversions=apiversions, branches=branches)

cli_manager = CLIManager(monolithe_config=self.config)
cli_manager.execute()
Expand Down
Loading