numpy-tutorials icon indicating copy to clipboard operation
numpy-tutorials copied to clipboard

Flatten directory structure: get rid of `site/` and move website to top-level

Open rossbar opened this issue 2 years ago • 2 comments

This is an idea inspired by #89. Currently, all the (non-executable) markdown source files for the website are stored in the site/ directory to keep the top-level directory tidy. However, the current organization also has unintended consequences, mostly due to the symbolic link back to the content/ dir:

  1. The use of symbolic links means the site can't be built on Windows
  2. The "edit this page" button is broken due to the symlink

The simplest way to fix the above issues would be to just do away with the site/ directory. That's what this PR proposes. The main downside is that the top-level directory becomes much more cluttered with sphinx-specific files/folders (e.g. _static) and site-specific files (e.g. all the .md files).

Are the benefits worth the tradeoff? Let me know what you think! In the meantime, I'm marking this as a draft.

PS - the diff is not very useful: you really need to be able to compare the old structure to the new. The easiest way to do so would be:

git add remote rossbar https://github.com/rossbar/numpy-tutorials
git fetch rossbar
git checkout --track rossbar/flatten-dir-structure

You can then bounce between main and flatten-dir-structure to see the impact on the top-level directory.

rossbar avatar Jan 16 '23 07:01 rossbar

I went ahead and rebased this one on main and will mark it as ready for review in case anyone wants to weigh in.

I moved the .md source files for the non-executable web pages to their a subdirectory (pages/) to help declutter the top-level directory. I also took the opportunity to rename content -> tutorials to better reflect what's inside the folders in the context of the new directory structure.

To summarize my take on this proposal:

Pros

  • Gets rid of symlinks, which makes this buildable on Windows and inside docker mounted volumes. Also fixes the "edit" button on the site

Cons

  • Clutters up the top-level directory somewhat.
  • The restructuring will cause merge conflicts for any open PRs which touch the tutorials (currently only 2)

rossbar avatar Jan 12 '24 21:01 rossbar

@rossbar - could you rebase again, please?

bsipocz avatar Jan 22 '24 20:01 bsipocz

I'm not sure how to proceed with this PR right now, maybe close and revisit after/during switching to mystjs, as I expect the switch requires some restructuring anyway.

bsipocz avatar Jul 15 '24 00:07 bsipocz

Agreed, the mystjs will indeed involve restructuring that supersedes this, so let's close it!

rossbar avatar Jul 15 '24 08:07 rossbar