Skip to content

Conversation

jtpio
Copy link
Member

@jtpio jtpio commented Oct 18, 2024

A couple of improvements to the docs setup:

  • Add hatch script to serve the docs
  • Use sphinx-autobuild to watch the docs
  • Remove the previous Makefile
  • Mention building the docs in CONTRIBUTING.md
  • Convert more .rst to .md
  • Remove "Background" from the nav bar, add "Changelog" and "FAQ" for visibility:

image

@jtpio jtpio added the documentation Improvements or additions to documentation label Oct 18, 2024
GitHub actions scripts are available to draft a changelog, draft a release, publish a release, and check a release.

See the [action details documentation](https://jupyter-releaser.readthedocs.io/en/latest/background/theory.html#action-details) for more information.
See the [action details documentation](https://jupyter-releaser.readthedocs.io/en/latest/reference/theory.html#action-details) for more information.
Copy link
Member Author

Choose a reason for hiding this comment

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

The check-links failure is expected, and should resolve itself after merging:

image

@jtpio jtpio marked this pull request as ready for review October 18, 2024 18:59
Copy link
Collaborator

Choose a reason for hiding this comment

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

Do we have to remove makefiles or is it just that there is a different way these are no longer needed? I just wonder how much of a burden keeping them is, it feels pretty standard to be able to use make for sphinx compliation.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think the motivation here was to to keep it simple and have the hatch scripts be the recommended way for building the docs. And ReadTheDocs can build the docs without the Makefiles.

Also Makefiles tend to look complicated (although it could be more of a personal opinion).

Copy link
Member Author

Choose a reason for hiding this comment

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

But if they are used by maintainers / contributors of this repo then we could keep them yes.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Also Makefiles tend to look complicated (although it could be more of a personal opinion).

True

But if they are used by maintainers / contributors of this repo then we could keep them yes.

I would probably switch to hatch commands, not sure about other contributors.

@jtpio
Copy link
Member Author

jtpio commented Oct 21, 2024

Thanks @krassowski for the review!

@jtpio jtpio merged commit 42a31f6 into jupyter-server:main Oct 21, 2024
17 of 19 checks passed
@jtpio jtpio deleted the docs-build-scripts branch October 21, 2024 14:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants