Skip to content

Doc generation #4

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

Closed
wants to merge 4 commits into from
Closed

Doc generation #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
23fb47e
C, RockyJS, and PKJS docs are all generated properly
FlynnD273 Mar 4, 2025
b8c4867
Android docs now work!
FlynnD273 Mar 5, 2025
b61b462
Fix brain typo
FlynnD273 Mar 5, 2025
e83e565
Merge branch 'main' into doc-generation
FlynnD273 Jul 20, 2025
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
1 change: 1 addition & 0 deletions .env.sample
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ ALGOLIA_API_KEY=
ALGOLIA_SEARCH_KEY=
ALGOLIA_PREFIX=devsite-dev-
GOOGLE_ANALYTICS=
GOOGLE_API=
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What uses this environment variable?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tbh I don't remember 😅 I don't think it's used currently.

ROLLBAR_CLIENT_TOKEN=
JEKYLL_ENV=development
SKIP_DOCS=false
7 changes: 6 additions & 1 deletion lib/c_docs/doc_member.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,12 @@ def process_data(node, mapping, platform)

def process_typedef(node, mapping, platform)
process_return_type(node, mapping, platform)
@data[platform]['argsstring'] = node.at_css('argsstring').content.to_s
argsstring = node.at_css('argsstring')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there issues with this path as is? I haven't run into errors in this path in my local testing, but it's entirely possible I missed something.

if argsstring == nil then
@data[platform]['argsstring'] = ""
else
@data[platform]['argsstring'] = argsstring.content.to_s
end
process_parameter_list(node, mapping, platform)
end

Expand Down
2 changes: 2 additions & 0 deletions lib/pebble_documentation_c.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ def cleanup
def download_and_extract(zip, folder)
open(zip) do | zf |
Zip::File.open(zf.path) do | zipfile |
print("extracted from ", zf.path)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: remove debug print

print("\n")
zipfile.each do | entry |
path = File.join(folder, entry.name).sub('/doxygen_sdk/', '/')
FileUtils.mkdir_p(File.dirname(path))
Expand Down
2 changes: 1 addition & 1 deletion lib/pebble_documentation_js.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ def process_members(js_module)
:properties => member['properties'],
:url => url,
:kind => kind,
:summary => member['summary']
:summary => member['memberof']
}
add_symbol(symbol)
js_module[:children].push(symbol)
Expand Down
5 changes: 3 additions & 2 deletions lib/pebble_documentation_pebblekit_android.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ def initialize(site, source)
@path = '/docs/pebblekit-android/'
open(source) do | zf |
Zip::File.open(zf.path) do | zipfile |
entry = zipfile.glob('javadoc/overview-summary.html').first
entry = zipfile.glob('javadoc/index.html').first
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This breaks doc generation for Android in my local testing. What was the motivation for this change?

summary = Nokogiri::HTML(entry.get_input_stream.read)
process_summary(zipfile, summary)

Expand All @@ -47,7 +47,8 @@ def language

def process_summary(zipfile, summary)
summary.css('tbody tr').each do | row |
name = row.at_css('td.colFirst').content
print(row)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: remove debug print

name = row.at_css('th.colFirst').content
package = {
name: name,
url: "#{@path}#{name_to_url(name)}/",
Expand Down
2 changes: 1 addition & 1 deletion plugins/generator_docs.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ def generate_docs
# The order of these functions will determine the order of preference
# when looking up symbols e.g. double backticks
# DO NOT CHANGE THE ORDER UNLESS YOU KNOW WHAT YOU ARE DOING
generate_docs_c
# generate_docs_c
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason this has been disabled? We definitely want this one enabled - don't want to be using the preview docs.

generate_docs_c_preview unless @site.data['docs']['c_preview'].nil?
generate_docs_rocky_js
generate_docs_pebblekit_js
Expand Down
43 changes: 23 additions & 20 deletions source/_includes/docs/menu.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,48 @@
{% comment %}
Copyright 2025 Google LLC
Copyright 2025 Google LLC
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you avoid reformatting the header blocks if possible? Just to keep diffs clean.


Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
{% endcomment %}

<ul>
{% for group in include.tree %}
{% for group in include.tree %}
{% if page.docs_language == 'pebblekit_ios' %}
{% assign open = true %}
{% assign open = true %}
{% elsif include.group.path contains group.name %}
{% assign open = true %}
{% assign open = true %}
{% else %}
{% assign open = false %}
{% assign open = false %}
{% endif %}
{% if group.children.size > 0 %}
<li class="section-menu__item{% if open == true %} open{% if include.group.path.last == group.name %} active{% endif %}{% endif %}">
<li
class="section-menu__item{% if open == true %} open{% if include.group.path.last == group.name %} active{% endif %}{% endif %}">
<a href="{{ group.url }}">{{ group.name }}</a>
{% if group.children.size > 0 %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced this is a necessary change - the only place I'm seeing it have an effect is in the Rocky docs, where it adds the timeout/interval functions to the sidebar. Those pages are very small though, and they're already documented on the Rocky docs index page, so I don't think that adds much value.

<ul>
{% for item in group.children %}
<li class="section-menu__subitem{% if include.group.path contains item.name %} open{% if include.group.path.last == item.name %} active{% endif %}{% endif %}">
{% for item in group.children %}
<li
class="section-menu__subitem{% if include.group.path contains item.name %} open{% if include.group.path.last == item.name %} active{% endif %}{% endif %}">
<a href="{{ item.url }}"><span>{{ item.name }}</span></a>
{% if item.children.size > 0 %}
<ul>
{% for child in item.children %}
{% capture full_url %}{{ child.url }}index.html{% endcapture %}
<li class="section-menu__subsubitem{% if page.url == full_url %} active{% endif %}"><a href="{{ child.url }}"><span>{{ child.name }}</span></a></li>
<li class="section-menu__subsubitem{% if page.url == full_url %} active{% endif %}"><a
href="{{ child.url }}"><span>{{ child.name }}</span></a></li>
{% endfor %}
</ul>
{% endif %}
</li>
{% endfor %}
{% endfor %}
</ul>
</li>
{% endif %}
Expand Down
104 changes: 55 additions & 49 deletions source/_layouts/docs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
Expand All @@ -17,65 +17,71 @@
menu_section: docs
search_primary: docs
---
<div class="section-menu section-menu--docs section-menu--dark">
<div class="section-menu__header">
{% case page.docs_language %}
{% when 'c' %}
<h3><a href="/docs/c/">Pebble C API</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'c_preview' %}
<h3><a href="/docs/c/preview/">Pebble C API (SDK 4 Preview)</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'rockyjs' %}
<h3><a href="/docs/rockyjs/">Pebble JavaScript API</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_js' %}
<h3><a href="/docs/pebblekit-js/">PebbleKit JS</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_ios' %}
<h3><a href="/docs/pebblekit-ios/">PebbleKit iOS</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_android' %}
<h3><a href="/docs/pebblekit-android/">PebbleKit Android</a><a href="#"><i class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% else %}
<h3><a href="/docs/">Documentation</a></h3>
{% endcase %}
<ul class="documentation-menu js-doc-menu">
<li><a href="/docs/c/">Pebble C API</a></li>
{% if site.data.docs_tree.c_preview %}
<li><a href="/docs/c/preview/">Pebble C API (preview)</a></li>
{% endif %}
<li><a href="/docs/rockyjs/">Pebble JavaScript API</a></li>
<li><a href="/docs/pebblekit-js/">PebbleKit JS</a></li>
<li><a href="/docs/pebblekit-ios/">PebbleKit iOS</a></li>
<li><a href="/docs/pebblekit-android/">PebbleKit Android</a></li>
</ul>
</div>
<div class="section-menu section-menu--docs section-menu--dark">
<div class="section-menu__header">
{% case page.docs_language %}
{% when 'c' %}
{% include docs/menu.html tree=site.data.docs_tree.c group=page.group %}
<h3><a href="/docs/c/">Pebble C API</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'c_preview' %}
{% include docs/menu.html tree=site.data.docs_tree.c_preview group=page.group %}
<h3><a href="/docs/c/preview/">Pebble C API (SDK 4 Preview)</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'rockyjs' %}
{% include docs/menu.html tree=site.data.docs_tree.rockyjs group=page.js_module %}
<h3><a href="/docs/rockyjs/">Pebble JavaScript API</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_js' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_js group=page.js_module %}
<h3><a href="/docs/pebblekit-js/">PebbleKit JS</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_ios' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_ios group=page.group %}
<h3><a href="/docs/pebblekit-ios/">PebbleKit iOS</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% when 'pebblekit_android' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_android group=page.group %}
<h3><a href="/docs/pebblekit-android/">PebbleKit Android</a><a href="#"><i
class="fa fa-chevron-down fa-lg documentation-menu__arrow js-doc-menu-toggle"></i></a></h3>
{% else %}
<ul>
<li class="section-menu__item"><a href="/docs/c/">Pebble C API</a></li>
{% if site.data.docs_tree.c_preview %}
<li class="section-menu__item"><a href="/docs/c/preview/">Pebble C API (preview)</a></li>
{% endif %}
<li class="section-menu__item"><a href="/docs/rockyjs/">Pebble JavaScript API</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-js/">PebbleKit JS</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-ios/">PebbleKit iOS</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-android/">PebbleKit Android</a></li>
<!--
<h3><a href="/docs/">Documentation</a></h3>
{% endcase %}
<ul class="documentation-menu js-doc-menu">
<li><a href="/docs/c/">Pebble C API</a></li>
{% if site.data.docs_tree.c_preview %}
<li><a href="/docs/c/preview/">Pebble C API (preview)</a></li>
{% endif %}
<li><a href="/docs/rockyjs/">Pebble JavaScript API</a></li>
<li><a href="/docs/pebblekit-js/">PebbleKit JS</a></li>
<li><a href="/docs/pebblekit-ios/">PebbleKit iOS</a></li>
<li><a href="/docs/pebblekit-android/">PebbleKit Android</a></li>
</ul>
</div>
{% case page.docs_language %}
{% when 'c' %}
{% include docs/menu.html tree=site.data.docs_tree.c group=page.group %}
{% when 'c_preview' %}
{% include docs/menu.html tree=site.data.docs_tree.c_preview group=page.group %}
{% when 'rockyjs' %}
{% include docs/menu.html tree=site.data.docs_tree.rockyjs group=page.js_module %}
{% when 'pebblekit_js' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_js group=page.js_module %}
{% when 'pebblekit_ios' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_ios group=page.group %}
{% when 'pebblekit_android' %}
{% include docs/menu.html tree=site.data.docs_tree.pebblekit_android group=page.group %}
{% else %}
<ul>
<li class="section-menu__item"><a href="/docs/c/">Pebble C API</a></li>
{% if site.data.docs_tree.c_preview %}
<li class="section-menu__item"><a href="/docs/c/preview/">Pebble C API (preview)</a></li>
{% endif %}
<li class="section-menu__item"><a href="/docs/rockyjs/">Pebble JavaScript API</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-js/">PebbleKit JS</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-ios/">PebbleKit iOS</a></li>
<li class="section-menu__item"><a href="/docs/pebblekit-android/">PebbleKit Android</a></li>
<!--
<li class="section-menu__item"><a href="/docs/web-timeline/">Timeline Web API</a></li>
<li class="section-menu__item"><a href="/docs/web-appglance/">AppGlance Web API</a></li>
-->
</ul>
{% endcase %}
</div>
</ul>
{% endcase %}
</div>
</div><!-- sidebar__wrapper -->
<div class="content content--section-menu">
{% include search.html %}
Expand Down
1 change: 0 additions & 1 deletion source/_sass/sections/documentation/android.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,6 @@
display:block;
float:left;
background-image:url(resources/titlebar.gif);
height:18px;
}
.overviewSummary .tabEnd, .packageSummary .tabEnd, .contentContainer ul.blockList li.blockList .tabEnd, .summary .tabEnd, .classUseContainer .tabEnd, .constantValuesContainer .tabEnd {
width:10px;
Expand Down
16 changes: 8 additions & 8 deletions source/docs/c/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,14 @@ <h1 class="pagetitle">{{ page.title }}</h1>
</p>

{% for module in site.data.docs_tree.c %}
<div class="docs__module">
<h4><a href="{{ module.url }}">{{ module.name }}</a></h4>
{% if module.summary.size > 0 %}
{{ module.summary }}
{% else %}
<p>&nbsp;</p>
{% endif %}
</div>
<div class="docs__module">
<h4><a href="{{ module.url }}">{{ module.name }}</a></h4>
{% if module.summary.size > 0 %}
{{ module.summary }}
{% else %}
<p>&nbsp;</p>
{% endif %}
</div>
{% endfor %}
</div>
</div>
Expand Down
Loading