Open stscicrawford opened 6 years ago
@eteq : Along the lines of @nden's suggestion about setting up environments: it might also be good to have a recommendation for setting up the development environment. E.g. "Use python setup.py develop if it's pure-python, or python setup.py build and run from the build directory if not. Use conda environments to manage dependencies."
I like the idea of including reference to such tools directly in the style guide, to keep that info in the same place as the style recommendations. I think that will be more helpful to more users if we say, e.g. "you should do X, and here is a tool that will help you automate doing X". Typically I don't think this would be detailed usage instructions or procedures for these tools, but rather a brief mention and hyperlink to point the reader to such descriptions elsewhere.
Ideally there might be distinctive formatting (perhaps a colored text box, a la what Sphinx's .. hint::
markup produces?) that would distinguish the "here is a helpful tool" text from the surrounding "here are some style recommendations" text. Not sure how best to do that formatting in Jupyter Markdown though; just direct HTML div/span and CSS code added in those cells?
One practical question that comes to mind - is this the right place to describe tools and procedures for configuring an environment to comply with these guides? Perhaps have a section at the end that links to existing descriptions of how to configure IDEs or editors to check for PEP8 compliance?