This repository has been archived by the owner on Oct 23, 2023. It is now read-only.
Fix the links in generated html files #168
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* Added handler for build finished event to fix doc links * Added contributing guide * Adding wait for the subprocess * Fixed the path issue with finding the script for fixing the links * Added darwin switch for sed -i flag * Fixed non darwin with -i flag for sed * Using find instead of xargs as it fails on readthedocs * Moving the substitution errors to /dev/null * Escaped the Link values Signed-off-by: Prafulla Mahindrakar <[email protected]>
pmahindrakar-oss
force-pushed
the
pmahindrakar/fix-doc-links
branch
from
896d2e1
to
73a7dcd
Compare
8 tasks
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
TL;DR
Following are the comments from CONTRIBUTING.MD file which also explaing the issue
Docs structure
The index.rst files for protos are kept in parallel folder structure under the docs folder.
All the proto definitions are within protos/flyteidl and there corresponding docs are kept in protos/docs
Each module in protos has same named module under the docs also.
eg : protos/flyteidl/core has same named doc structure placing it index and other documentation files in protos/docs/core
Docs Generation
Currently pseudomuto/protoc-gen-doc is being used for generating the MD files which are placed in protos/docs and corresponding folder based on the module
protoc-gen-doc generates a single MD file if we include all the protos and doesn't provide a way to split these.
The MD files are then fed as input to sphinx for html doc generation
Inorder to modularize this and not have one single huge html file the MD files are being generated per module(eg :core,admin,plugin)
But due to this process if there references in html/md files which don't exist in the same file then they lead to broken links.
eg: If we generate admin docs through this process , they would generate admin.md file in protos/docs/admin folder but if they reference docs from core
like for flyteidl.core.ResourceType then they would try to find it in the same MD/html file which wont be available
Inorder to fix this issue an additional post build step has been added to fix such links.
Check conf.py for sphinx to see build-finished event handler
Note : The plan is to move to generating RST file instead of MD files once this PR is checkedin pseudomuto/protoc-gen-doc#440 (comment)
which would simplify the doc generation further
Tested in docs-staging
https://docs.flyte.org/projects/flyteidl/en/docs-staging/
Type
Are all requirements met?
Complete description
How did you fix the bug, make the feature etc. Link to any design docs etc
Tracking Issue
https://github.com/lyft/flyte/issues/
Follow-up issue
NA
OR
https://github.com/lyft/flyte/issues/