Add Sphinx Documentation

[ericpien]

Changes

• yfinance/doc contains /source with the configuration and the template rsts.
• Updated README and docstrings

Current Workflow

• push to dev-documented branch will trigger yfinance/.github/workflows/deploy_doc.yml
• deploy_doc.yml configured to build the documentation from yfinance/doc and publish the htmls to documentation branch's docs directory.
• This will update the documentation as set up in the repo's settings/pages.

Relates to https://github.com/ranaroussi/yfinance/discussions/1330

[ValueRaider]

The action claims success: https://github.com/ranaroussi/yfinance/actions/runs/11690739308 But link is 404

What is your source set to? yfinance might be the opposite. This is my menu from yfinance-cache:

[ericpien]

My setting is the same and set to Deploy from a branch.

I think I found the problem: Apparently the publishing branch has to be created by GitHub Actions, not manually created.

Tested and confirmed as below:

1. I manually created a branch documentation_manual and pushed to my fork's dev-documentation and published to documentation_manual/docs. This resulted in the same behavior in which only non-html subset of filers were copied.
2. I did not manually create the branch documentation_generated and pushed again to my fork's dev-documentation and published to documentation_generated/docs. This correctly copied the full repo including the htmls.

Can I submit another PR to this branch and try to publish to a non-existing branch via GitHub Actions?

[ValueRaider]

Understood. I've reverted documentation and renamed to docs_markdown, so name documentation should be free.

[ericpien]

Thank you. Are you able to re-run https://github.com/ranaroussi/yfinance/actions/runs/11690726258? If not, I can submit a trivial PR targetting dev-documented to retrigger and try to publish to documentation.

[ValueRaider]

I triggered your action again https://github.com/ranaroussi/yfinance/actions

But this didn't then trigger a new deployment https://github.com/ranaroussi/yfinance/deployments/github-pages

[ericpien]

I tried to replicate it on my end and noticed renaming a branch 1. unpublishes the page and 2. reassigns the deploying branch to the renamed branch so now we need to push to docs_markdown to deploy.

So the workflow requires us to publish to a new branch created by GitHub Actions. But we are unable to assign the deploying branch to this new branch.. Are we absolutely restricted from changing the deploying branch/dir?

[ValueRaider]

Only @ranaroussi can access settings page.

Is an option just dumping the html files into docs folder of deploy branch? Like I did here: https://github.com/ValueRaider/yfinance-cache/blob/5ab1bb4b17df9d134e745fb3fa27123b0f9951e2/make-docs.sh#L33

[ericpien]

Yeah that works. I worked out an example in my fork: Upon push to docs_markdown branch (i.e. merge PR), the htmls are built and committed to docs_markdown branch's /docs directory then the page is deployed.

So based on that, I expect the PR https://github.com/ranaroussi/yfinance/pull/2115/ to do the same for ranaroussi::docs_markdown/docs

I think this is a pretty good alternative since we can push changes to docs_markdown during development, and eventually simply push the new changes from main.

[ericpien]

For continuity, I'll leave the comment here.

Following the PR #2115 to docs_markdown, every file needed was built and uploaded to docs/ but the page build was not triggered in actions.

This is odd as a new commit to the renamed publishing branch (i.e. docs_markdown) should have triggered a new build. I tested this behavior by renaming my fork's publishing branch to docs_markdown_renamed and merging a PR that resulted in automatic rebuild and documentation is available.

@ranaroussi are you able to give us a peek at the settings/pages configuration like below?

[ValueRaider]

While we wait for Ran, for a plan B are you OK with README linking to your fork? Maybe you just need to click sync fork to trigger redeploys.

[ranaroussi]

Done.

Thank you all for the great work 🙏