spacetelescope / style-guides

An opinionated guide on how we work.
Creative Commons Attribution 4.0 International
55 stars 33 forks source link

Add tools, procedures, and environment #15

Open stscicrawford opened 6 years ago

stscicrawford commented 6 years ago

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?

stscicrawford commented 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."

mperrin commented 6 years ago

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?