While following the instructions to contribute to the translation of the audio course project into Portuguese (Brazilian), as outlined in this issue, I encountered a few issues with the doc-builder tool.
After forking the audio course project and installing doc-builder to use its preview command, I noticed some unexpected behavior. Firstly, the doc-builder preview was running on port 5173, whereas the audio course README indicated it should be on port 3000.
Additionally, I faced a significant issue with error 404 when trying to navigate through the project using links on the main page. The Table of Contents (TOC) was visible, but any attempts to access the links resulted in a 404 error, suggesting that the linked pages were not being served properly.
Upon investigating, I theorized that these issues might stem from changes between versions 0.4 and 0.5 of the doc-builder. This led me to consider the need to open an issue with the audio course repository to ensure compatibility with doc-builder version 0.5.
However, the primary concern that brings me here appears to be related to the doc-builder itself. In the utils.js file, there's a function called get_cached_repo, which is triggered when the "kit" folder is missing. This function is supposed to fetch a copy of the "kit" folder from the repository, a process that works well with the latest version of doc-builder.
The issue arises when using a previous version of doc-builder, as required by the audio course project. Installing version 0.4.0 via pip (pip install doc-builder==0.4.0) mistakenly downloads the "kit" folder intended for version 0.5.0, leading to the same 404 errors encountered with version 0.5.0, as if the pip installation was not respecting the specified version.
To prevent such mismatches in future releases, I propose an adjustment in the cloning operation within the get_cached_repo function to include a version-specific parameter, such as git clone --branch v + __version__, where __version__ is the installed package version. Given that doc-builder maintains tags for each release, this modification would ensure the download mechanism always retrieves the correct version of the "kit" folder corresponding to the installed package version, enhancing compatibility and reliability.
While following the instructions to contribute to the translation of the audio course project into Portuguese (Brazilian), as outlined in this issue, I encountered a few issues with the doc-builder tool.
After forking the audio course project and installing doc-builder to use its preview command, I noticed some unexpected behavior. Firstly, the doc-builder preview was running on port 5173, whereas the audio course README indicated it should be on port 3000.
Additionally, I faced a significant issue with error 404 when trying to navigate through the project using links on the main page. The Table of Contents (TOC) was visible, but any attempts to access the links resulted in a 404 error, suggesting that the linked pages were not being served properly.
Upon investigating, I theorized that these issues might stem from changes between versions 0.4 and 0.5 of the doc-builder. This led me to consider the need to open an issue with the audio course repository to ensure compatibility with doc-builder version 0.5.
However, the primary concern that brings me here appears to be related to the doc-builder itself. In the
utils.jsfile, there's a function calledget_cached_repo, which is triggered when the "kit" folder is missing. This function is supposed to fetch a copy of the "kit" folder from the repository, a process that works well with the latest version of doc-builder.The issue arises when using a previous version of doc-builder, as required by the audio course project. Installing version 0.4.0 via pip (
pip install doc-builder==0.4.0) mistakenly downloads the "kit" folder intended for version 0.5.0, leading to the same 404 errors encountered with version 0.5.0, as if the pip installation was not respecting the specified version.To prevent such mismatches in future releases, I propose an adjustment in the cloning operation within the
get_cached_repofunction to include a version-specific parameter, such asgit clone --branch v + __version__, where__version__is the installed package version. Given that doc-builder maintains tags for each release, this modification would ensure the download mechanism always retrieves the correct version of the "kit" folder corresponding to the installed package version, enhancing compatibility and reliability.