Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[📝] Autogenerate Documentation #184

Closed
wants to merge 8 commits into from

Conversation

natmfat
Copy link

@natmfat natmfat commented Jan 24, 2024

I added pdoc in a GitHub Action to automatically generate documentation when the main branch changes. Here's a preview on my fork.

NOTE:
This will require enabling GitHub Pages in settings so the documentation will automatically be deployed (replace the test branch with "main" instead, example of settings shown below).

image

@JacobGlennAyers
Copy link
Contributor

Seems to be missing the first argument in every function -
In this example, the local_scores is not formatted the same way as the others
image

@JacobGlennAyers
Copy link
Contributor

The returns is also formatted differently

@natmfat
Copy link
Author

natmfat commented Jan 24, 2024

My bad I forgot to tell it to use Google-style docstrings (made a new commit, looks like this since it'll take a few minutes to build/deploy:)
image

.github/workflows/docs.yml Outdated Show resolved Hide resolved
jobs:
# Build the documentation and upload the static HTML files as an artifact.
build:
runs-on: windows-latest
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally, we would prefer jobs run on ubuntu-latest unless you absolutely need Windows.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used ubuntu-latest but I couldn't figure out this error

terminate called after throwing an instance of 'std::runtime_error'
  what():  random_device could not be read
/home/runner/work/_temp/aa96a6f4-a556-45f5-a8b1-05d0770bba35.sh: line 1:  1882 Aborted                 (core dumped) poetry run python -m pdoc ./PyHa -o docs/
Error: Process completed with exit code 134.

I suspect it has something to do with this issue but I figured generating docs worked on my machine (windows) so it would work on the action

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add an issue to PyHa referencing that issue then resolve this conversation.

pyproject.toml Outdated Show resolved Hide resolved
.github/workflows/docs.yml Outdated Show resolved Hide resolved
.github/workflows/docs.yml Show resolved Hide resolved
PyHa/__init__.py Outdated Show resolved Hide resolved
PyHa/__init__.py Outdated Show resolved Hide resolved
- Remove np-generate-docs
- If statement in action
- Move pdoc to dev dependencies
- Badge in README
- Edit links
@natmfat natmfat requested a review from ntlhui January 24, 2024 17:27
README.md Show resolved Hide resolved
deploy:
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This and line 9 are redundant!

Comment on lines +41 to +53
deploy:
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This repo already has a GitHub Pages deployment! @sprestrelski @Sean1572 please reconcile this!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you modify pyproject.toml, you need to update poetry.lock using poetry lock!

@natmfat natmfat closed this by deleting the head repository Oct 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants