-
Notifications
You must be signed in to change notification settings - Fork 25
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
Add API reference generated by Sphinx #212
Open
Hoolean
wants to merge
6
commits into
harfbuzz:main
Choose a base branch
from
Hoolean:sphinx-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+247
−0
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
6c991df
Add API reference generated by Sphinx
Hoolean 73edc81
Restrict star-exports to objects defined in this module
Hoolean c92572a
Change author based on PR feedback
Hoolean 4d02b4b
Pin Sphinx requirements for reproducible builds
Hoolean 38ef9e8
Add Read the Docs configuration file
Hoolean dcf7c27
Install self as package to facilitate API reference discovery
Hoolean File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
# Read the Docs configuration file for Sphinx projects | ||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
|
||
# Required | ||
version: 2 | ||
|
||
# Set the OS, Python version and other tools you might need | ||
build: | ||
os: ubuntu-24.04 | ||
tools: | ||
python: "3.12" | ||
|
||
# Build documentation in the "docs/" directory with Sphinx | ||
sphinx: | ||
configuration: docs/conf.py | ||
# Fail on all warnings to avoid broken references | ||
# TODO: Enable after README and repack_with_tag() warnings are corrected | ||
# fail_on_warning: true | ||
|
||
# Optional but recommended, declare the Python requirements required | ||
# to build your documentation | ||
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html | ||
python: | ||
install: | ||
- requirements: docs/requirements.txt | ||
- requirements: requirements.txt | ||
- method: pip | ||
path: . |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
/build/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
Sphinx >= 7.4.7 | ||
sphinx-rtd-theme >= 2.0.0 | ||
myst-parser >= 4.0.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
# | ||
# This file is autogenerated by pip-compile with Python 3.12 | ||
# by the following command: | ||
# | ||
# pip-compile requirements.in | ||
# | ||
alabaster==0.7.16 | ||
# via sphinx | ||
babel==2.16.0 | ||
# via sphinx | ||
certifi==2024.8.30 | ||
# via requests | ||
charset-normalizer==3.3.2 | ||
# via requests | ||
docutils==0.20.1 | ||
# via | ||
# myst-parser | ||
# sphinx | ||
# sphinx-rtd-theme | ||
idna==3.10 | ||
# via requests | ||
imagesize==1.4.1 | ||
# via sphinx | ||
jinja2==3.1.4 | ||
# via | ||
# myst-parser | ||
# sphinx | ||
markdown-it-py==3.0.0 | ||
# via | ||
# mdit-py-plugins | ||
# myst-parser | ||
markupsafe==2.1.5 | ||
# via jinja2 | ||
mdit-py-plugins==0.4.2 | ||
# via myst-parser | ||
mdurl==0.1.2 | ||
# via markdown-it-py | ||
myst-parser==4.0.0 | ||
# via -r requirements.in | ||
packaging==24.1 | ||
# via sphinx | ||
pygments==2.18.0 | ||
# via sphinx | ||
pyyaml==6.0.2 | ||
# via myst-parser | ||
requests==2.32.3 | ||
# via sphinx | ||
snowballstemmer==2.2.0 | ||
# via sphinx | ||
sphinx==7.4.7 | ||
# via | ||
# -r requirements.in | ||
# myst-parser | ||
# sphinx-rtd-theme | ||
# sphinxcontrib-jquery | ||
sphinx-rtd-theme==2.0.0 | ||
# via -r requirements.in | ||
sphinxcontrib-applehelp==2.0.0 | ||
# via sphinx | ||
sphinxcontrib-devhelp==2.0.0 | ||
# via sphinx | ||
sphinxcontrib-htmlhelp==2.1.0 | ||
# via sphinx | ||
sphinxcontrib-jquery==4.1 | ||
# via sphinx-rtd-theme | ||
sphinxcontrib-jsmath==1.0.1 | ||
# via sphinx | ||
sphinxcontrib-qthelp==2.0.0 | ||
# via sphinx | ||
sphinxcontrib-serializinghtml==2.0.0 | ||
# via sphinx | ||
urllib3==2.2.3 | ||
# via requests |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Configuration file for the Sphinx documentation builder. | ||
# | ||
# For the full list of built-in configuration values, see the documentation: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
|
||
# -- Project information ----------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
||
project = "uharfbuzz" | ||
copyright = "2024, Adrien Tétar" | ||
author = "HarfBuzz Contributors" | ||
|
||
# -- General configuration --------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration | ||
|
||
extensions = [ | ||
"sphinx.ext.autodoc", | ||
"myst_parser", | ||
] | ||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output | ||
|
||
html_theme = "sphinx_rtd_theme" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
uharfbuzz documentation | ||
======================= | ||
|
||
.. include:: ../../README.md | ||
:parser: myst_parser.sphinx_ | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Contents: | ||
|
||
reference |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
API Reference | ||
============= | ||
|
||
.. automodule:: uharfbuzz | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All the
ot_*
functions above are deprecated, do we still need to include them here?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've just tested locally, and if we exclude the functions here they will be excluded from documentation, but would also be excluded from any existing star-imports (i.e.
from uharfbuzz import *
), and so it would be a breaking change.Maybe this is okay if we release explicitly as breaking and there are alternatives though? (or even as v1.0.0, if the module enjoys any production use?)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Alternatively there may be a way to make them show as deprecated in Sphinx
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(in some ways, even adding
__all__
at all is already a breaking change, but the only variables being excluded at the moment are re-exports from uharfbuzz's dependencies and the standard library, which I think we can consider a bug fix)