python style guide

[stscicrawford]

Create a style guide outlining best practices for writing python code and packages

[stscicrawford]

cc: @nden @eteq @bourque

[bourque]

For what it's worth, here is the style guide that is used for the jwql project. It doesn't discuss packaging practices, but perhaps a decent starting point?

[mperrin]

Various relatively minor points on the current draft Python style guide.

• "The Python ecosystem is shared one". Missing word 'a' before 'shared'.
• "opeinging up Python" Typo
• In the Style section, there is inconsistent language. The first paragraph says that the PEP8 guidelines "are not absolutes, but rather guidelines". But immediately after that it says "The following exceptions are allowed" which implies no other exceptions are allowed at all.
  • "should have automatically build documentation" should say 'built' instead
  • "hosted automatically on servcies like ReadTheDocs or internal STScI services." First, 'servcies' has a typo. Secondly I would be interested in hearing more about the internal service options for doc hosting; is there any internal equivalent to readthedocs for hosting documentation from projects on Gitlab? If so it would be good to provide a how-to for that here, or link to that info elsewhere.
  • "documnentation" typo.
  • I agree with the statement that notebooks in the docs should be included in the automatically built docs! This could helpfully refer to the nbsphinx Sphinx extension in addition to plain nbconvert.
  • In the recommended template packages it says "astropy template package with STSci specific changes", but does not explain what specific changes are intended.

[pllim]

Re: nbconvert -- It does add onto maintenance burden, especially if you host it on RTD, as it requires more than sphinx as doc build dependencies, and requires those to play well with RTD. For example, if your notebooks take too long to render, you might run over the 900s limit (or is it 450s?) on RTD server and get timed out error.

[pllim]

This issue is too broad. There are now several pages on different aspects of Python coding and packaging. Any remaining concerns should be separate issue(s).