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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Jazzy Docs #2250

Merged
merged 4 commits into from Aug 22, 2017

Conversation

Projects
None yet
3 participants
@aamctustwo
Contributor

aamctustwo commented Aug 21, 2017

Issue Link 馃敆

Goals 鈿斤笍

  • Add documentation to the repo rather than using (the now deprecated) CocoaDocs

Implementation Details 馃毀

  • Adds docs folder with Jazzy generated documentation
  • Adds Jazzy as a developer dependency (via Bundler)
  • Update the readme to point to GitHub Pages (when it is configured in repo's settings) for locally generated Jazzy docs instead of CocoaDocs as it is now deprecated

Testing Details 馃攳

View documentation:

  • Open index.html in the docs folder in a browser

Generate documentation:

  • Run bundle exec jazzy in the root directory of the project

Notes 鈿狅笍

  • To use GitHub Pages for the Jazzy documentation, the repo's settings needs to be updated after merging into master. There's an option in the GitHub Pages configuration to adjust the publishing source to master branch /docs folder. See the GitHub Pages documentation.

aamctustwo added some commits Aug 21, 2017

Add Jazzy for documentation
- Adds Jazzy as a developer dependency using Bundler
- Configures Jazzy for Alamofire

Jazzy repo: https://github.com/realm/jazzy
Update readme to use Jazzy docs
Update the readme to point to GitHub Pages (when it is configured in repo's settings) for locally generated Jazzy docs instead of CocoaDocs as it is now deprecated.
@jshier

Looks great! I think we could merge this even before Alamofire 5.

Show outdated Hide outdated Gemfile Outdated
author_url: http://alamofire.org/
github_url: https://github.com/Alamofire/Alamofire
module: Alamofire
output: docs

This comment has been minimized.

@jshier

jshier Aug 21, 2017

Contributor

We probably want to refactor our Documentation layout with this. Perhaps we can put these docs in Documentation/jazzy and move the migration guides Documentation/Migration Guides. That will require some Xcode project changes for the guides, but there's no need to add the jazzy docs to Xcode at all.

@jshier

jshier Aug 21, 2017

Contributor

We probably want to refactor our Documentation layout with this. Perhaps we can put these docs in Documentation/jazzy and move the migration guides Documentation/Migration Guides. That will require some Xcode project changes for the guides, but there's no need to add the jazzy docs to Xcode at all.

This comment has been minimized.

@cnoon

cnoon Aug 22, 2017

Member

After more investigation, it looks like it has to go in the master branch in a docs folder to work seamlessly with GitHub Pages. We can sort out where we put everything else in another PR. Might not really be that big of a deal to have a docs directly full of Jazzy docs and then a Documentation folder with everything else nested.

@cnoon

cnoon Aug 22, 2017

Member

After more investigation, it looks like it has to go in the master branch in a docs folder to work seamlessly with GitHub Pages. We can sort out where we put everything else in another PR. Might not really be that big of a deal to have a docs directly full of Jazzy docs and then a Documentation folder with everything else nested.

This comment has been minimized.

@jshier

jshier Aug 22, 2017

Contributor

Sounds good.

@jshier

jshier Aug 22, 2017

Contributor

Sounds good.

Show outdated Hide outdated Gemfile.lock Outdated
Show outdated Hide outdated README.md Outdated

@jshier jshier requested a review from cnoon Aug 21, 2017

@jshier jshier added this to the 4.6.0 milestone Aug 21, 2017

@cnoon

This comment has been minimized.

Show comment
Hide comment
@cnoon

cnoon Aug 22, 2017

Member

So for my own clarification, would our release workflow change from the last commit being updating the version and finalizing the CHANGELOG to updating the Jazzy docs using bundler? I would assume we'd always want the docs to represent the latest officially released version...but maybe that's not a good assumption.

On a separate note, thanks for putting this together @aamctustwo! 馃嵒

Member

cnoon commented Aug 22, 2017

So for my own clarification, would our release workflow change from the last commit being updating the version and finalizing the CHANGELOG to updating the Jazzy docs using bundler? I would assume we'd always want the docs to represent the latest officially released version...but maybe that's not a good assumption.

On a separate note, thanks for putting this together @aamctustwo! 馃嵒

@cnoon

Overall, changes look great @aamctustwo. Once you get these minor comments addressed we can get this merged and cut the 4.6.0 release. 馃憤馃徎

Show outdated Hide outdated .jazzy.yaml Outdated
Show outdated Hide outdated README.md Outdated
author_url: http://alamofire.org/
github_url: https://github.com/Alamofire/Alamofire
module: Alamofire
output: docs

This comment has been minimized.

@cnoon

cnoon Aug 22, 2017

Member

After more investigation, it looks like it has to go in the master branch in a docs folder to work seamlessly with GitHub Pages. We can sort out where we put everything else in another PR. Might not really be that big of a deal to have a docs directly full of Jazzy docs and then a Documentation folder with everything else nested.

@cnoon

cnoon Aug 22, 2017

Member

After more investigation, it looks like it has to go in the master branch in a docs folder to work seamlessly with GitHub Pages. We can sort out where we put everything else in another PR. Might not really be that big of a deal to have a docs directly full of Jazzy docs and then a Documentation folder with everything else nested.

@aamctustwo

This comment has been minimized.

Show comment
Hide comment
@aamctustwo

aamctustwo Aug 22, 2017

Contributor

@cnoon Yes, I'd recommend the final step to be updating the docs.

It might be worth raising a new issue to update the CONTRIBUTING.md file or add a new file in docs/Documentation to write out the release process as it begins to add more steps (as well as looking to possibly script some of the steps).

Contributor

aamctustwo commented Aug 22, 2017

@cnoon Yes, I'd recommend the final step to be updating the docs.

It might be worth raising a new issue to update the CONTRIBUTING.md file or add a new file in docs/Documentation to write out the release process as it begins to add more steps (as well as looking to possibly script some of the steps).

Update and lint configurations
Responding to PR feedback on #2250

- Adds spacing in array in `.jazzy.yaml` file
- Adds `.ruby-gemset` and `.ruby-version` files for Ruby version managers
- Adds `cocoapods` as an explicit Ruby dev dependency
- Updates Bundler lock to latest version of Bundler
- Updates Readme to use lower-case `ttps://alamofire.github.io`
@jshier

jshier approved these changes Aug 22, 2017

@cnoon

cnoon approved these changes Aug 22, 2017

Great work here @aamctustwo...thanks again! 馃嵒

@cnoon cnoon merged commit 318e590 into Alamofire:master Aug 22, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@cnoon

This comment has been minimized.

Show comment
Hide comment
@cnoon
Member

cnoon commented Aug 22, 2017

@aamctustwo aamctustwo referenced this pull request Aug 23, 2017

Closed

Add Jazzy Docs #2224

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment