connorgoggins opened a new issue #17798: [Website 2.0] Versioned Dropdown for Python API Docs URL: https://github.com/apache/incubator-mxnet/issues/17798 ## Description Currently, the MXNet Python API Docs on the website only show functions corresponding to the latest master API. The current version of the website also does not label the API version being used. This leads to frustration from the developer community, as the API functions and tutorials may work differently for older MXNet releases. This means that the current version of the Python docs can be considered broken, as developers using older versions of the API may experience errors simply by following the docs and tutorials as they are written and may decide that MXNet is broken. At this point in time, there is no way for users to access older versions of the docs, or even to see which version of MXNet is described by the docs on the website. ## Proposed Resolution To remedy this issue, the Python API version referenced by the docs should be clearly visible and users should be able to easily navigate between different API versions using a dropdown menu. These changes will be made in the interest of making the website more useful for MXNet developers by adding important missing functionality and content. Feedback from the community regarding the proposed implementation is welcome. ## Stakeholders @sandeep-krishnamurthy @aaronmarkham @szha @sojiadeshina ## Proposed Implementation When the user navigates to the Python API Reference homepage (https://mxnet.apache.org/api/python/docs/api/), the title of the page will be changed from the current “Python API” to “Python API v1.6 (stable)”, where 1.6 represents the latest stable release of MXNet. They will see a version dropdown to the right of the “Python API” text in the header: <img width="939" alt="Screen Shot 2020-03-06 at 12 50 12 PM" src="https://user-images.githubusercontent.com/25328906/76270047-10067680-6231-11ea-99f0-7d72f2783df6.png";> <img width="950" alt="Screen Shot 2020-03-06 at 12 52 49 PM" src="https://user-images.githubusercontent.com/25328906/76270055-1694ee00-6231-11ea-8ca0-2dfaaa62981f.png";> Note: in the final version, the dropdown menu will be properly styled with CSS in a manner that is consistent with the rest of the docs. The URL path for the default Python API docs root will change from /api/python/docs/api/index.html to /api/python/docs/api/*stable*/index.html. This format will be consistent for all Python API doc pages under the root, as well as for other API versions (e.g. for v1.1, root URL will be /api/python/docs/api/v1.1/index.html). The dropdown will default to the latest stable release (e.g. “v1.6 (stable)”, and the version options available will be determined by the contents of a config.json file located at docs/generation/config.json. This JSON file will designate the API release versions available for each language API, so the valid version options will depend on which language docs the user is navigating. The dropdown and its value (pulled from the URL) will persist as the user navigates through the docs for the chosen language. To generate old versions of the Python docs, Sphinx will be run on each old release branch once and the corresponding HTML doctree will be generated. The doctree will then be compressed and stored on S3, and the Makefile for the Python docs will be revised to pull down all past artifacts from S3 and unzip them into their associated API version directories (e.g. /api/python/docs/api/v1.1/). The current master will continue to be generated by Sphinx at compile time. Since the only version of the docs that will be rebuilt after each change to the MXNet repository is the current master, all tutorials will now correspond to the master version of the API. ## Deliverables 1. PR for New Python API Docs Website with API Version Dropdown ## Acceptance Criteria 1. Dropdown should allow users to seamlessly switch between API versions from within the Python API docs 2. All other navigation functionality within the Python API docs website should be preserved 3. Styling should be consistent with the current version of the Python API docs website
---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to 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
![https://user-images.githubusercontent.com/25328906/76270047-10067680-6231-11ea-99f0-7d72f2783df6.png"](https://user-images.githubusercontent.com/25328906/76270047-10067680-6231-11ea-99f0-7d72f2783df6.png"){kind=link}
![https://user-images.githubusercontent.com/25328906/76270055-1694ee00-6231-11ea-8ca0-2dfaaa62981f.png"](https://user-images.githubusercontent.com/25328906/76270055-1694ee00-6231-11ea-8ca0-2dfaaa62981f.png"){kind=link}