Refactor README.md to align with notebook workflow and fix outdated content

[divine7022]

The README currently:

• Points to the deprecated PHP web UI as "the fastest way to begin modeling"
• Links to an outdated tutorials page
• Has broken links
• Doesn't points to our new notebook-based tutorials

Tasks

1. Replace "Web Interface demo" section with "Getting Started"

Lead with our new notebook tutorials:

• https://pecanproject.github.io/pecan-documentation/develop/rendered-demo-notebooks/run_pecan.html
• https://pecanproject.github.io/pecan-documentation/develop/rendered-demo-notebooks/uncertainty.html

Add a note that the PHP web interface is now considered legacy and is no longer the recommended entry point. Clearly mark web UI as not the recommended workflow

2. Fix broken documentation links

Examples:

• Current (broken): https://pecanproject.github.io/documentation.html
• Fixed: https://pecanproject.github.io/documentation/

3. Fix grammatical issues in Documentation section

Rewrite with parallel structure. Add reference to pkgdown docs ( package documentations )
https://pecanproject.github.io/package-documentation/develop/

[Sahilxrajput]

Hi @divine7022, can I work on this issue? Could you assign it to me?

[AritraDey-Dev]

@divine7022 PTAL at #3610

The first point you mentioned is a duplicate of #3610.

Also, simply removing the web PHP docs and redirecting to the Quarto HTML pages is not necessarily the right solution. I’m still discussing with David whether we should remove the PHP section entirely or add a separate section that redirects to the Quarto pages. Nothing is finalized yet.

So it would be better if you remove the first point from the issue for now.

[divine7022]

Thanks for the heads up @AritraDey-Dev ; here i would strongly lean toward not creating equal sections for web + notebook in README, since the web ui is deprecated. instead :

• make notebook tutorials the primary recommended starting point
• keep the PHP web ui link, but clearly labeled as legacy

I defer this to @dlebauer

[AritraDey-Dev]

Also, the broken-links note you mentioned is no longer necessary, since we now have the GitHub Action at
https://github.com/PecanProject/pecan/blob/develop/.github/workflows/check-links.yml

to automatically check for broken links. We also have issue #3710 to track all current broken links.

[mdietze]

@AritraDey-Dev the decision on the last PEcAn call was to remove the PHP from the README and to add the Quarto notebook as the prefered entry point into learning PEcAn. It was not to have two sections. If the PHP portal is mentioned at all in the README it should be as deprecated.

And having a new tool that finds broken links does not mean that new issues should not mention the need to fix them!

[dlebauer]

@mdietze Just to summarize from last week's PEcAn meeting and webUI deprecation timeline, my recollection is that we decided to:

• remove the pointer to the webUI from the README, and for the next release only link to notebooks from the tutorials page
• defer scrubbing webUI from the docs entirely until perhaps PEcAn v2.0

[mdietze]

Correct, for the current release candidate (v1.10.0) we're having the README point to the notebooks instead of the webUI, but deferring the complete removal of the webUI and associated docs, likely until v2.0

[infotroph]

for the current release candidate (v1.10.0)

Logistical note: This means the PR for this should be directed into branch release/v1.10.0 rather than develop.

[S1DDHEY]

Hi @divine7022 , I’d like to work on this issue.

Based on the discussion, I’ll:

• remove the Web UI pointer from the README
• make notebook tutorials the primary recommended entry point
• avoid broader Web UI doc cleanup until v2.0

Let me is there something else that I should take care of while fixing this.

[S1DDHEY]

@divine7022 The PR #3730 has been merged you can close the issue if there are no other improvements needed.

[divine7022]

@S1DDHEY thanks for the nudge