Improve pkgdown build process and fix documentation generation

[divine7022]

Improve pkgdown build process and fix documentation generation

Review Time Estimate: Within one week, Types of changes: Bug fix (non-breaking change which fixes an issue) #18

Description

• Correct Documentation Generation: Fixed script/build_pkdown.R to ensure pkgdown::build_site() correctly generates documentation within the correct package directories. This resolves issues where documentation was not being created for some packages.
• Symlink Handling: Ensured symlinks are preserved during the copy process from docs to book_source/pkgdocs. This prevents broken assets (CSS, JavaScript, images) in the final documentation.
• Robustness and Error Handling: Improved error handling in build_pkdown.R to prevent failures for individual packages from halting the entire build process. The script now includes a tryCatch block with a finally clause for proper working directory management, and it stops execution on critical errors.
• Package Structure Updates: Updated the package structure for base, models, modules, and book_source to align with the new build process.
• File Inclusion: Included the necessary files: scripts/build_pkgdown.R, Makefile, book.yml, docker/base/dockerfile, and docker-compose.yml.
• Book Integration: Ensured pkgdown output is correctly copied to book_source/pkgdocs for seamless integration into the bookdown site.

Motivation and Context

This change is required to ensure that the pkgdown documentation for all PEcAn packages is generated correctly and consistently. Previously, issues with symlink handling and incorrect working directory management led to broken documentation and missing files. This PR addresses these problems, providing a more robust and reliable documentation build process. It also automates the process of copying the generated documentation to the bookdown source directory, simplifying the integration of pkgdown output into the book.

Review Time Estimate

• Immediately
• Within one week
• When possible

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• My name is in the list of CITATION.cff
• I agree that PEcAn Project may distribute my contribution under any or all of
  • the same license as the existing code,
  • and/or the BSD 3-clause license.
• I have updated the CHANGELOG.md.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[divine7022]

@dlebauer Let me know if any further modification are needed.
Waiting for your feedback.

Thankyou!.

[robkooper]

Looking at the PR it is massive, any reason why all the doc folders are comitted?

[divine7022]

@robkooper sir,
Thanks for the feedback, I understand the concern about the size of the PR due to the doc folders. I will remove them and ensure the PR focuses only on the essential files required for the build: script/build_pkgdown.R, Makefile, book.yml, docker/base/dockerfile, and docker-compose.yml.

Please let me know if you have any further suggestions.