search

tudat-team / tudat-space

An introduction and guide to tudat-space.
https://tudat-space.readthedocs.io
14 stars 17 forks source link

File tree refactoring #93

Closed sbcowan closed 1 year ago

sbcowan commented 1 year ago

This pull request (initiated by issue #80) has no significant content changes. It consists of some extensive source filename refactoring to resemble the tudat-space headers more closely. Navigating through the source code with the website side-by-side is now significantly easier.

A few notes:

  1. I don't know if this is a known thing, but with more substantial refactoring, test builds had a peculiar bug: When navigating to certain files on tudat-space, other toc elements on tudat-space would not show up. I solved this by rebuilding using the -E option to activate a full rebuild, rather than a partial one.
  2. There is a 'secret menu' in tudat-space, where some files (two_body_dynamics.rst for example) don't show up anywhere in the build, but can be found when using the search function. Is something meant to be done with this file (I refer to this later)?
  3. For future development of the tudat-space website (and any other documentation website), there should be a system for creating new documentation, namely by creating new files, as opposed to updating existing files but change its contents. The latter saves time in the short term, but is less clear the longer this is done.
  4. Jupyterlab notebooks refer to file names on the tudat-space website, as opposed to referencing within the rst source. This means that there can be a discrepancy between the file names that are referenced in the jupyterlab notebooks (they generally reference the 'latest' version) and recently changed filenames, until the changes have been published to the designated reference point of the jupyterlab notebook.
  5. Last but not least, I think, if everyone agrees, that I should perform another similar refactor. However this regards both the directory tree in the source code as well as the toc as it is visible on tudat-space, so further discussion is needed. A number of things are still jumbled around, and structured somewhat chaotically:
    • Files like ephemerides.rst, two_body_dynamics.rst, and auto_processing.rst are 'ghost' files, they exist, some have content, others don't, but they are not used. This unnecessarily clutters the source code tree. I think that WIP files should be kept on separate branches or on local versions of tudat-space (clones/forks), and that old files should be moved when overshadowed, albeit to a deprecated/ directory.
    • Some elements on tudat-space (available_models.rst, for example) are in a subdirectory of a file, but in the source code they exist in the same list as the parent file. This also adds to a unstructured file tree, but it is a more fundamental change to the structure, which is why I wanted feedback first.
    • Similarly, the acceleration_models directory is a directory of files that all exist in translational, yet the directory is on the same level as the dynamics_types directory (which is where translational.rst is in). Idem, less clear structure.

Sorry in advance for the many file changes, it was unavoidable ;)