aaronmarkham opened a new pull request #11916: [MXNET-371] Sphinx error reduction URL: https://github.com/apache/incubator-mxnet/pull/11916 ## Description ## This PR reduces the number of Sphinx errors and warnings from 1628 to 251 on a full Sphinx build. It reduces the warnings from a Sphinx toctree being missing from 170 to 0 on incremental Sphinx builds. ## Checklist ## ### Essentials ### Please feel free to remove inapplicable items for your PR. - [x] The PR title starts with [MXNET-$JIRA_ID], where $JIRA_ID refers to the relevant [JIRA issue](https://issues.apache.org/jira/projects/MXNET/issues) created (except PRs with tiny changes) - [x] Changes are complete (i.e. I finished coding on this PR) - [ ] All changes have test coverage: **The customizations in docs/_static/js/sidebar.js do not appear to have any tests or documentation. This PR disables some of its functionality as it behaves erratically and causes problems with the Sphinx's documented (default) behavior.** - [ ] Code is well-documented: Much of the Sphinx setup is undocumented already. **This PR helps cleanup some of problems to pave the way for a better understanding of how the parts work together, and how they might be updated or replaced.** - [x] To the my best knowledge, examples are either not affected by this change, or have been fixed to be compatible with this change - Check the API doc at http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-$PR_ID/$BUILD_ID/index.html **Note**: while this might provide a simple preview and help test the left nav and toctree features, I'd advise looking at a full site build with the versions dropdown. ### Changes ### 1. docs/get_started folder is deleted: it only held a redirect which already being handled by [.htaccess](https://github.com/apache/incubator-mxnet-site/blob/asf-site/.htaccess#L3). Removing it reduces warnings/errors. 1. docs/architecture/release_note_0_9.md is deleted: it was the only legacy release note. Release notes are held on the [releases page](https://github.com/apache/incubator-mxnet/releases). Removing it reduces warnings/errors. 1. Sphinx's `docs/conf.py` updates: - `exclude_patterns` : added these to reduce warnings/errors: ['build_version_doc' (working dir), 'api/python/model.md' (depricated), 'README.md' (not needed for Sphinx's indexing)] - update config to the working Sphinx version 1.5.6 - update config to 2018 copyright - update config to have correct project URL 1. I disabled/removed some functionality it `docs/_static/js/sidebar.js`. I was able to find some info about it by digging through old commits and PRs, but many of the PRs and commits have no description or commit message. I can see that the functionality may have been of some benefit before where it magically modified the output of Sphinx. However, since it wasn't documented, this caused me hours of frustration when Sphinx's documented behavior was being nullified by this client-side activity. - Replaying the previous sidebar layout and merging with the existing one plays havoc with the UI after one has gone through and configured the toctree for each folder. This is why I removed it. It is possible if the original authors took a look, they could update it, but for reasons I outline later, I think it would be better to remove it. - Adding Clojure to the nav can come in a separate PR. But since I was in the sidebar already, I added it. 1. Added new index pages where ones were missing or modified existing ones. This is generally a good practice for SEO, and drastically improves the warnings/errors situation. - I used the `:hidden:` directive for `tutorials` and `faq` as they already have custom indexes, but were the source of many warnings/errors. - I skipped modifying index pages that did not result in warnings/errors. - I used the `:glob:` pattern where I could to auto-index a folder. This works best when there are no subfolders to index. You can see this mostly in the tutorials section. : ``` .. toctree:: :glob: * ``` ## Comments ## - As we gear up for foreign translations of the site, I really can't see how undocumented, custom client-side overrides are going to be maintainable. We should work within the features of the site generator. I recommend we try to fix the site at it's core and as part of a regular build pipeline, and remove these kind of "magical" features. - There is additional complexity with the versions dropdown that seems to be covered in the sidebar logic. Disabling this client-side hack might result in uncovering more issues and entanglements. I'd appreciate any SMEs to assist figuring out solutions that can help simply things and get us ready for internationalization of the site.
---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
