Final Sphinx documentation w/ ReadTheDocs #172
Conversation
facebook-github-bot
added
the
CLA Signed
|
@jbitton has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
The reason for the above issue occuring seems due to the way we create
Possible solution: Detecting if "readthedocs.org" is in the filepath, and if so, render the substring after "/latest" |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
17 similar comments
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@jbitton has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator. |
1 similar comment
|
@jbitton has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator. |
|
lil update: @iAdityaEmpire, your fix for version.txt worked! let us know when you've updated this for the rest of the files zoe listed :) |
|
@jbitton Haha I think that was Zoe who updated the version.txt file, I was at school during the time. I'll be able to fix the existing issues by the end of day today. |
|
ohhh lol i didn't notice. okay, sounds good! no rush :) |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@jbitton has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator. |
docs/source/augly.image.rst
Outdated
| Subpackages | ||
| ----------- | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 4 | ||
|
|
||
| augly.image.utils |
There was a problem hiding this comment.
since augly.image.utils doesn't exist anymore as an .rst file, should this be deleted too?
There was a problem hiding this comment.
@jbitton Yep I'll delete that
| @@ -0,0 +1,109 @@ | |||
| augly.text.augmenters package | |||
There was a problem hiding this comment.
since we deleted the other augmenters .rst files, let's delete this one too for consistency
docs/source/augly.text.rst
Outdated
| Subpackages | ||
| ----------- | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 4 | ||
|
|
||
| augly.text.augmenters |
There was a problem hiding this comment.
and then make sure to remove this as well as necessary
docs/source/augly.text.rst
Outdated
|
|
||
| .. automodule:: augly.text.utils | ||
| :members: | ||
| :undoc-members: | ||
| :show-inheritance: |
There was a problem hiding this comment.
make sure to remove this :D
docs/source/augly.video.rst
Outdated
| Subpackages | ||
| ----------- | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 4 | ||
|
|
||
| augly.video.augmenters |
There was a problem hiding this comment.
make sure to remove augmenters since it doesn't exist anymore
@iAdityaEmpire just flagging that FYI this error is still happening when we import the diff! Did you try the solutions I suggested up here? |
|
@zpapakipos Oh that's weird -- I did try using |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@jbitton has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator. |
|
@iAdityaEmpire has updated the pull request. You must reimport the pull request before landing. |
|
@jbitton has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator. |
There was a problem hiding this comment.
@iAdityaEmpire this all looks amazing!!!! all the tests on the Meta side have passed successfully!!! thank you so much for all of your extra work to get this done :)
|
Thanks @jbitton! Glad to help. |
Summary
<Please summarize what you are trying to achieve, what changes you made, and how they acheive the desired result.>
What This Is
This is comprehensive documentation for AugLy with Sphinx docstring formatting under the hood with a Read the Docs theme to make augmentation parameters, return types, etc more readable and user-friendly.
How It Works
Sphinx is a documentation generator commonly used by the Python community. It also has its own docstring format.
Internal AugLy docstrings utilize tags such as
@paramor@returnsfor labeling due to internal Facebook convention. However, Sphinx does not recognize these tags, opting for:in favor of@, among other changes.Luckily for us, Python docstring format
epytextis very similar to AugLy (credit @Cloud9c), meaning that we can claim that we use epytext formatting and then convert it tosphinxwhen necessary.Another problem: Sphinx requires explicit types labeled in the form of
:typeand:rtypeto display types once documentation is rendered. However, Python typehints (which AugLy uses generously) are not natively supported. Therefore we use an extension to Sphinx that autodetects typehints and adds them on the fly.In the end, Sphinx uses the module structure specified in
docs/sourcewith rST (filetype similar to Markdown) to generate a table of contents for our final documentation.How to Build Documentation Locally
git clone github.com/facebookresearch/AugLycd docs && pip install -r requirements.txtdocssubdirectory. Then runmake htmlto generate documentation. If you want to delete all these later, you can runmake clean.docs/buildand openindex.htmlGenerating new documentation later
auglysubdirectory and add their.rstfiles accordingly, but the process of detection needs to be triggered manually. Runsphinx-apidoc -o ./source ../auglyin the root directory to do so, and update thetoctreeinindex.rstif necessary.Integration with ReadTheDocs
.readthedocs.ymlfile specifies the configuration for these builds. By defaultffmpegandlibsndfile1are based on C and are required as prerequisites before requirements indocs/requirements.txtare installed (as RTD uses Ubuntu behind the scenes).docssubdirectory at all, so all are read from the source folder. Updating the docstrings inaugly/<modality>will be sufficient.