Move EasyDiffraction Library Docs from EasyDiffractionLibDocs to docs/ in EasyDiffractionLib
#168
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
tools/prepare_docs.sh
Outdated
| echo "\033[0;33m:::::: Create the mkdocs.yml configuration file\033[0m" | ||
| cp ../assets-docs/mkdocs.yml mkdocs.yml | ||
| echo "" >> mkdocs.yml | ||
| cat docs/mkdocs.yml >> mkdocs.yml |
There was a problem hiding this comment.
isn't just
cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml
simpler?
There was a problem hiding this comment.
This is definitely much simpler. Thank you!
| 'pytest-cov', # Coverage | ||
| 'pytest-xdist', # Enable parallel testing | ||
| 'ruff', # Linting and formatting code | ||
| 'validate-pyproject[all]', # Validate pyproject.toml |
There was a problem hiding this comment.
Do we still need npm and prettier with validate-pyproject?
There was a problem hiding this comment.
I guess they are aimed at two different things - validate-project checks if the yml file is of valid syntax, while prettier checks/fixes the layout.
There was a problem hiding this comment.
Exactly. Plus, Prettier is used for all non-Python file types.
DEVELOPMENT.md
Outdated
| cp -R examples/ docs/examples/ | ||
| cp ../assets-docs/mkdocs.yml mkdocs.yml | ||
| echo "" >> mkdocs.yml | ||
| cat docs/mkdocs.yml >> mkdocs.yml |
There was a problem hiding this comment.
or maybe replace this set of commands with asking users/devs to run tools/prepare_docs.sh instead?
There was a problem hiding this comment.
Purpose of DEVELOPMENT.md
The idea behind DEVELOPMENT.md was to provide a single, comprehensive example of the full development process, outlining all the possible steps along with their short descriptions. This serves as a quick reference for anyone looking to get an overview of the development workflow in one place, without needing to dig into multiple files.
- It acts as a simple guide, tested on macOS, though it might require adaptations for Windows and other environments.
- It eliminates the need to open individual shell scripts to understand how each step is actually implemented.
- This makes it a useful starting point for new contributors or for anyone needing a quick refresher on specific steps in the development process.
Regarding the Collection of Build Scripts (tools/*.sh)
The build scripts were originally just a personal simplification for my workflow. However, they would also need adjustments for Windows and similar environments. This raises the question: Are they necessary here at all?
Redundancy with GitHub Workflows (.github/workflows/*.yml)
- All these above steps are already covered in the
.github/workflows/*.ymlfiles. - These workflows are well-structured into separate files, jobs, and steps, with clear comments on each action.
- Technically, having them should be sufficient, as they already document the process in an actionable way.
However, finding the right workflow file, locating the correct job, and identifying the required step can sometimes be cumbersome. In contrast, having everything summarized in DEVELOPMENT.md makes it much easier to quickly refresh one's memory about the process.
Final Thoughts
Both tools/*.sh scripts and DEVELOPMENT.md effectively duplicate .github/workflows/*.yml, which means additional maintenance is required to keep everything in sync.
- Keeping
DEVELOPMENT.mdstill seems valuable as a quick reference guide. - The shell scripts (
tools/*.sh) should either be deleted or refactored to be called directly from the GitHub workflow YAML files, reducing redundancy.
| rm -rf node_modules/ | ||
| rm mkdocs.yml | ||
| rm package-lock.json | ||
| rm package.json |
There was a problem hiding this comment.
same here - maybe just reference tools/cleanup_docs.sh
There was a problem hiding this comment.
Check out my reply above.
.github/workflows/build-docs.yml
Outdated
| cp assets-branding/EasyDiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png | ||
| mkdir -p overrides/.icons/ | ||
| cp assets-branding/EasyDiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg | ||
| cp assets-branding/EasyScience/icons/es-icon_bw.svg overrides/.icons/easyscience.svg |
There was a problem hiding this comment.
These preparatory steps are present in tools/prepare_docs.sh - why not just run this script here?
(and for all other steps, which have corresponding scripts)
There was a problem hiding this comment.
Check out my reply above.
|
|
||
| on: | ||
| # Trigger the workflow on push | ||
| push: |
There was a problem hiding this comment.
Build docs on each push? We mostly do code changes and silly ruff fixes. Maybe have this run on master and develop only? If we need to write new docs and check them before pushing to develop, we can always trigger the docs rebuild manually.
There was a problem hiding this comment.
No, this is something I forgot to change after debugging the workflow. Thanks for noticing!
This pull request moves the EasyDiffraction Library documentation from the separate repository EasyDiffractionLibDocs to the
docs/directory within the EasyDiffractionLib repository.Reasoning
Simplified Project Structure
Integrating the documentation within the main repository streamlines the overall structure of the EasyScience organization.
Improved Maintainability
Keeping the documentation alongside the source code ensures easier updates, better consistency, and reduced overhead in maintaining a separate repository.
Automated Documentation Builds
developormasterbranches.