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.

Sign up for GitHub

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

Jump to bottom

Create user-facing docsite using Sphinx #472

Closed
7 tasks
kaxil opened this issue Jun 20, 2022 · 1 comment · Fixed by #488
Closed
7 tasks

Create user-facing docsite using Sphinx #472

kaxil opened this issue Jun 20, 2022 · 1 comment · Fixed by #488
Assignees
@dimberman
Labels
documentation Improvements or additions to documentation
Milestone
1.0.0

Comments

@kaxil
Copy link
Collaborator

kaxil commented Jun 20, 2022 •
edited
Loading

Use Sphinx and Sphinx auto-api extension to autogenerate docs that adds:

  • Changelog
  • Reference Guide (Concepts)
  • Setup & Installation instructions
  • Tutorial / Quick Start

Note: You can reuse TUTORIAL.md and REFERENCE.md by converting them into rst and including the rest using the include directive (eg.".. include:: ../README.rst" )

References:

Subtasks

  • Add CI step to Build docs so each PR is tested with docs.
  • Fix any failures when building the docs -- mostly around docstrings or missing descriptions
  • Instructions or automation around building the docs locally (nox or Makefile etc)

Follow-up task: #276
This was referenced Jun 20, 2022
Closed
Closed
@kaxil kaxil added the documentation Improvements or additions to documentation label Jun 20, 2022
@kaxil kaxil added this to the 1.0.0 milestone Jun 20, 2022
@kaxil kaxil changed the title Create docsite using Sphinx Create user-facing docsite using Sphinx Jun 20, 2022
@kaxil kaxil mentioned this issue Jun 20, 2022
Closed
dimberman added a commit that referenced this issue Jun 23, 2022
@dimberman
Create sphinx documentation for readthedocs (#484)
c2dc6f2 
# Description
## What is the current behavior?
Currently there is no readthedocs site for the Astro SDK. This means that users need to read through our github (which is unindexed) or our codebase to know wh

<!--
Issues are required for both bug fixes and features.
Reference it using one of the following:

closes: #276  and #472
-->


## What is the new behavior?
Now we can use sphinx-autoapi and sphinx to automatically generate documentation for us based on our function and class comments. While this is not NEARLY sufficient as total documentation, it is still a huge step forward.

## Does this introduce a breaking change?
No

### Checklist
- [x] Created tests which fail without the change (if possible)
- [x] Extended the README / documentation, if necessary
@kaxil
Copy link
Collaborator Author

kaxil commented Jun 23, 2022

This task is not complete, please check the Issue description

@kaxil kaxil reopened this Jun 23, 2022
@kaxil kaxil mentioned this issue Jun 23, 2022
Merged
2 tasks
@dimberman dimberman mentioned this issue Jun 23, 2022
Merged
2 tasks
dimberman added a commit that referenced this issue Jul 5, 2022
@dimberman @sunank200 @kaxil
Improve Sphinx docs - Adds changelog & reference guides (#488)
4b18664 
Address @kaxil comments for #[472](#472)
Currently our documentation does not contain all files and has a few formatting errors.

closes: #472

Addresses formatting errors and @kaxil comments and add .md files to our readthedocs for better documentation coverage.

- [x] Created tests which fail without the change (if possible)
- [x] Extended the README / documentation, if necessary

Co-authored-by: Ankit Chaurasia <8670962+sunank200@users.noreply.github.com>
Co-authored-by: Kaxil Naik <kaxilnaik@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@dimberman dimberman

Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
1.0.0
Development

Successfully merging a pull request may close this issue.

Improve Sphinx docs - Adds changelog & reference guides astronomer/astro-sdk
2 participants
@dimberman @kaxil