Conversation
Generate one navigation data file and lazily render namespace branches. Keep a static class index for crawlability and offline fallback, and refresh navigation data with live-preview changes. Amp-Thread-ID: https://ampcode.com/threads/T-01a0ea31-9f66-7342-a269-34772e5428db Co-authored-by: Stanislav Katkov <krooni@skatkov.com>
Documentation previewCommit: |
| </summary> | ||
|
|
||
| <%= generate_class_index_content(@classes, rel_prefix) %> | ||
| <ul id="class-navigation" class="link-list nav-list"></ul> |
There was a problem hiding this comment.
Darkfish generator had a id='navigation' element, so I decided not to risk any possible collisions and call this class-navigation.
There was a problem hiding this comment.
There shouldn't be any risk of collisions here as darkfish & aliki templates should never be rendered together. I'd prefer using clear naming unless we found in some cases there's a collision, but that'd be a separate bug to fix.
There was a problem hiding this comment.
That said, let's use namespace-navigation for this id instead?
| assert_equal 'text/html', content_type | ||
| end | ||
|
|
||
| def test_search_data_refreshes_after_file_changes |
There was a problem hiding this comment.
Why is this test needed for the changes made here?
There was a problem hiding this comment.
It was to ensure that the search index is getting properly refreshed locally if the server is running (e.g. so navigation will be updated as well). I have removed it.
| return | ||
| end | ||
|
|
||
| class RDocGeneratorAlikiNavigationTest < Test::Unit::TestCase |
There was a problem hiding this comment.
I don't feel these tests are providing much value as they target very specific implementation behaviour.
I know we don't have browser e2e tests as a better alternative now, but I'd rather not adding these.
There was a problem hiding this comment.
Sounds good. I removed it
| </span> | ||
| </summary> | ||
|
|
||
| <%= generate_class_index_content(@classes, rel_prefix) %> |
There was a problem hiding this comment.
Will this method still be needed?
There was a problem hiding this comment.
This method is still used in the Darkfish generator.
The Darkfish generator has same problem as well as Aliki. But because Darkfish is already deprecated, I assume there is no need to do similar changes to Darkfish.
Problem
Aliki currently rebuilds and embeds the complete class/module navigation tree in every generated page.
My build servers can't handle
google-api-gemgeneration, they always time out. I tried running it locally, and it was running for ~5 hours and never finished. By the time I got annoyed and stopped, the generation folder had 234GB of data.Every HTML page was ~6 MB in size.
Solution
We can have a shared navigation section shared across all documentation pages. That would remove 97% of data from every page in case of
google-api-gem.We already have
search_data.indexfile, which could be used to reconstruct navigation section with JavaScript.Results
After implementing these changes, I've seen the following results for
google-api-gemgem.For other gems, that are not that extremely big in contents, performance savings are more modest.
The current branch generated the site about 0.22 s faster (~3.4%) for rdoc's source code.