Documenting such a thing is a very good idea. However, isn't that what the "API" sections in the main doc are for? I would argue that it is better to improve the API section rather than hiding such valuable info in a README. Just a thought.

While we're talking about documentation for developers, where is the doc for making a new or bug fix release, or for backporting? I think that would be very nice to have too.

@pllim - I think there's a difference between explaining how the code is structured and the API docs - the latter is intended for users who want to find out about options to pass to functions etc, and the former is really just intended for people who want to work on the code.

We don't have good docs for backporting etc. yet...

@astrofrog , if not in the API section, then maybe a new section in the "developer guidelines" to list the info by sub-package, or such. My point is that it is more visible as part of the actual doc, than README. That's my opinion, but if it is just me, then never mind.

@pllim - I agree, this could go in a dedicated section of the docs.

Another idea -- If you want to keep README, is to do some Sphinx magic so that the new section auto-extracts the README contents from each sub-package directory. But perhaps that would require README to be in RST format, not MD.

I agree that having a standardized section in the Sphinx docs for each subpackage would be the way to go. It's a little more work than a plain readme but it gives the opportunity to include API links and embedded images showing design concepts etc.

It should definitely be picked up by sphinx, but I think there is a lot of benefit of having it right in the code directory too -- first place someone will look! So, I second @pllim's idea of some sphinx magic that includes these files.

I'm not sure I see the value in finding the sphinx magic to include RST doc pages from outside of the docs/ tree, and whether we even want to really go down that path. This also limits the design docs to being a single RST doc and leaves the open question of where to put supporting media like PNG images.

We can leave a sufficient breadcrumb without any of this magic by having a README file that says (for example):

For code design documentation see 
http://astropy.readthedocs.io/en/latest/table/implementation_details.html

As seen for Table, there is already a precedent set for code design docs in the Sphinx docs. Once you have gone to the trouble of making Sphinx docs, then it is usually worth seeing the rendered HTML version instead of the raw RST.

I think I'm convinced by @taldcroft that the documentation should stay in one place, the doc-tree. I would argue not to wait for a standardized format to appear, but rather put what you have there. Modeling is sufficiently complex that as is, few people are going to be willing to dive in and fiddle with the code.

I was reminded of the general issue of it being hard to know where to start coding in #6448, where @eteq had initially proposed to make a change in coordinates that went via a work-around that was unnecessary, as it had been previously addressed. I think this indicates that even for those that work a lot with the code, it has become hard to keep up and it would be very useful to have more information at hand. Partially, we can do that by adding comments liberally, but I think extra information such as the README proposed here is also very useful.

While initially I agreed that stuff should remain in the documentation tree, #6448 made me reconsider: documentation that really deals with code is perhaps better kept close, to reduce the risk that it becomes out of date. So, I have a different suggestion of where to put it: let's use the docstrings of the modules themselves. So far, these are mostly unused, but they do get typeset [1], and are close to the code. For this particular PR, it would imply moving the text to become part of __init__.py, perhaps under an Implementation header.

[1] An exception is in fact coordinates: http://docs.astropy.org/en/latest/coordinates/index.html#reference-api
But I think in that case too, additional text following an Implementation header would make sense.

I like the idea of using __init__.py for a description of the general layout and design of a package. Specific design notes can go in the related module docstrings. In the case of modeling fitting specific notes can go in fitting.py.

Hi humans 👋 - this pull request hasn't had any new commits for approximately 1 year, 4 months. I plan to close this in a month if the pull request doesn't have any new commits by then.

In lieu of a stalled pull request, please close this and open an issue instead to revisit in the future. Maintainers may also choose to add keep-open label to keep this PR open but it is discouraged unless absolutely necessary.

If you believe I commented on this issue incorrectly, please report this here.

⏰ Time's up! ⏰

I'm going to close this pull request as per my previous message. If you think what is being added/fixed here is still important, please remember to open an issue to keep track of it. Thanks!

If this is the first time I am commenting on this issue, or if you believe I closed this issue incorrectly, please report this here.