feat: smart handling of views

[jaredwray]

Please check if the PR fulfills these requirements

• Followed the Contributing and Code of Conduct guidelines.
• Tests for the changes have been added (for bug fixes/features) with 100% code coverage.

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
With this change we are removing the need to set homePage to false.

• if you have a readme.me at the root it will show the default home page home.hbs view
• if you do not have the readme.md in the root the default page will be docs
• if you do not have the readme.md, or docs, it will then show the api reference as the root

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances Docula's user experience by automating the selection of the default landing page. By intelligently detecting the presence of a README.md file, documentation, or an API specification, Docula can now dynamically set the site's root view. This change simplifies project setup, eliminates a previously required configuration option, and provides a more intuitive content-driven approach to site presentation.

Highlights

• Automatic Starting View Detection: Docula now intelligently determines the site's starting view based on available content, removing the need for manual configuration.
• Deprecation of homePage Option: The homePage configuration option has been deprecated. Docula will log a warning if this option is still used.
• Content Prioritization: The new logic prioritizes a root README.md for the home.hbs view, then the first documentation page if no README.md exists, and finally the API reference page if neither a README.md nor documentation is present.
• API Page Refactoring: API page rendering logic has been refactored to allow the API page to serve as the site's home page when other content is absent.

Changelog

• init/docula.config.mjs
  • Removed commented-out homePage option.
• init/docula.config.ts
  • Removed commented-out homePage option.
• site/docs/configuration.md
  • Removed documentation for the homePage option from the configuration table.
• site/docs/index.md
  • Updated documentation to reflect the new automatic starting view detection logic.
  • Removed the homePage: false code example.
• site/docs/multiple-pages.md
  • Updated instructions for setting the root home page by removing README.md.
  • Removed the homePage: false code example.
• src/builder.ts
  • Refactored home page rendering logic to prioritize README, documentation, or API content.
  • Introduced a hasReadme flag in DoculaData to indicate the presence of a root README.md.
  • Updated error messages for missing home page content.
  • Refactored API page building into a reusable renderApiContent method and a dedicated buildApiHomePage method.
  • Removed homePage property from DoculaData initialization.
• src/init.ts
  • Updated base64 encoded default configuration files to remove the homePage option.
• src/options.ts
  • Removed the homePage property and its JSDoc from DoculaOptions.
  • Added a deprecation warning that logs to the console if the homePage option is provided.
• templates/classic/home.hbs
  • Updated home page template to conditionally display documentation and API reference links based on available content.
• templates/modern/home.hbs
  • Updated home page template to conditionally display documentation and API reference links based on available content.
• test/builder.test.ts
  • Added new test fixtures for API-only and empty sites.
  • Updated existing tests to align with the new automatic view detection and homePage deprecation.
  • Adjusted test descriptions and expected error messages.
  • Added new tests for the automatic API home page rendering.
• test/docula.test.ts
  • Updated test descriptions and removed assertions related to the deprecated homePage option.
• test/fixtures/api-only-site/.gitignore
  • Added .cache to gitignore.
• test/fixtures/api-only-site/api/swagger.json
  • Added a sample swagger.json file for API-only site testing.
• test/fixtures/api-only-site/logo.svg
  • Added a logo SVG file for the API-only site fixture.
• test/fixtures/empty-site/.gitignore
  • Added .cache to gitignore.
• test/fixtures/empty-site/logo.svg
  • Added a logo SVG file for the empty site fixture.
• test/fixtures/mega-page-site-no-home-page/docula.config.mjs
  • Removed the homePage option from the test fixture configuration.
• test/fixtures/multi-page-site/README.md
  • Added a README.md file to the multi-page site fixture.
• test/options.test.ts
  • Removed tests for homePage option functionality.
  • Added a test to verify a deprecation warning is logged when homePage is provided.

Activity

• No specific activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (59b30c1) to head (83a66d7).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #363   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            7         7           
  Lines         1808      1818   +10     
  Branches       514       514           
=========================================
+ Hits          1808      1818   +10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

The homePage configuration option has been deprecated and removed in favor of an automatic content detection mechanism for determining the site's starting view. The system now prioritizes rendering a README.md as the home page, followed by the first documentation page if no README.md exists, or an API page if api/swagger.json is present and no other content is found. This involved refactoring the home page build logic in DoculaBuilder, updating data structures to use hasReadme instead of homePage, modifying templates to conditionally display content based on hasDocuments and hasApi flags, and updating related documentation and tests to reflect these changes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f940ec8901

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".