Replace handmade api docs with autogenerated api docs#637
Conversation
|
One thing this PR has made me notice is that some modules in chaco explicitly define chaco/chaco/plot_containers.py Lines 45 to 50 in fdd858a As a result, in this particular case, the base class |
|
@rahulporuri I am going to hold up on the follow up PR for now as I want to discuss with you more. We had said offline that we could list these classes in their corresponding pages of he usermanual which makes sense, but what about the corresponding section of the Commonly used Modules and Classes page, as that appears to be sort of the point of that page. |
rahulporuri
left a comment
rahulporuri
left a comment
There was a problem hiding this comment.
The autogenerated docs themselves look good but there are a couple of comments :
- can we use the api docs templates (like we do in e.g. traits-futures)
- can we also ignore the
chaco.tests_with_backendmodule when autogenerating the docs?
rahulporuri
left a comment
rahulporuri
left a comment
There was a problem hiding this comment.
Still LGTM with a couple of comments
| # Remove any previously autogenerated API documentation. | ||
| doc_api_files = os.listdir(api_path) | ||
| permanent = ['chaco.api.rst', 'templates'] | ||
| previously_autogenerated = \ | ||
| [file for file in doc_api_files if file not in permanent] | ||
| for file in previously_autogenerated: | ||
| os.remove(os.path.join(api_path, file)) |
There was a problem hiding this comment.
This might be overkill but okay (not an actionable comment). I guess this is needed if we rename modules and dont do git clean locally between docs builds.
2 participants
This PR replaces the hand curated api docs in the api reference with the autogenerated api docs. It then deletes the files for the hand made api docs.
This PR drastically decreases the number of warnings issued when building the docs from 1000+ down to now ~30.
In a follow up PR (possibly to sit on top of this branch), I will take the lists of links to important objects from these remove hand curated api doc files, and add those lists to the corresponding section of the user manual. Having these clear listings is useful but we don't need the redundancy.
UPDATE:
This PR now uses api docs templates following the lead of PRs enthought/envisage#339 and enthought/traits-futures#181