Add Jazzy Docs #2250

ghost · 2017-08-21T07:48:31Z

Issue Link 🔗

Add Jazzy Docs #2224

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.

- Adds Jazzy as a developer dependency using Bundler - Configures Jazzy for Alamofire Jazzy repo: https://github.com/realm/jazzy

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.

jshier · 2017-08-21T19:54:55Z

Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "jazzy"


If we're adding a Ruby environment, can you add cocoapods to the Gemfile, and add .ruby-version (2.4.1) and .ruby-gemset (alamofire) files too? That way it will integrate with RVM / rbenv automatically.

jshier · 2017-08-21T19:59:15Z

.jazzy.yaml

+author_url: http://alamofire.org/
+github_url: https://github.com/Alamofire/Alamofire
+module: Alamofire
+output: docs


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.

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.

Sounds good.

jshier · 2017-08-21T19:59:40Z

Gemfile.lock

+  jazzy
+
+BUNDLED WITH
+   1.14.5


Please use the latest bundler.

jshier · 2017-08-21T20:01:01Z

README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://travis-ci.org/Alamofire/Alamofire.svg?branch=master)](https://travis-ci.org/Alamofire/Alamofire)
 [![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Alamofire.svg)](https://img.shields.io/cocoapods/v/Alamofire.svg)
 [![Carthage Compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
-[![Platform](https://img.shields.io/cocoapods/p/Alamofire.svg?style=flat)](http://cocoadocs.org/docsets/Alamofire)
+[![Platform](https://img.shields.io/cocoapods/p/Alamofire.svg?style=flat)](https://Alamofire.github.io/Alamofire)


It will be a lower case alamofire.github.io.

cnoon · 2017-08-22T05:26:39Z

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. 👍🏻

cnoon · 2017-08-22T05:23:12Z

.jazzy.yaml

+module: Alamofire
+output: docs
+theme: fullwidth
+xcodebuild_arguments: [-workspace,'Alamofire.xcworkspace',-scheme,'Alamofire iOS']


Spaces after the commas?

cnoon · 2017-08-22T05:27:26Z

README.md

@@ -45,7 +45,7 @@ Alamofire is an HTTP networking library written in Swift.
 - [x] TLS Certificate and Public Key Pinning
 - [x] Network Reachability
 - [x] Comprehensive Unit and Integration Test Coverage
- [x] [Complete Documentation](http://cocoadocs.org/docsets/Alamofire)
+- [x] [Complete Documentation](https://Alamofire.github.io/Alamofire)


Lowercase as @jshier mentioned earlier.

cnoon · 2017-08-22T05:29:46Z

.jazzy.yaml

+author_url: http://alamofire.org/
+github_url: https://github.com/Alamofire/Alamofire
+module: Alamofire
+output: docs


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.

ghost · 2017-08-22T07:06:48Z

@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).

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`

cnoon

Great work here @aamctustwo...thanks again! 🍻

cnoon · 2017-08-22T23:37:39Z

We're live! http://alamofire.github.io/Alamofire/index.html

Aaron McTavish added 3 commits August 21, 2017 08:37

Add Jazzy for documentation

d3dd4df

- Adds Jazzy as a developer dependency using Bundler - Configures Jazzy for Alamofire Jazzy repo: https://github.com/realm/jazzy

Generate initial Jazzy docs

963c626

Update readme to use Jazzy docs

c130bf2

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 requested changes Aug 21, 2017

View reviewed changes

jshier requested a review from cnoon August 21, 2017 20:01

jshier added this to the 4.6.0 milestone Aug 21, 2017

cnoon requested changes Aug 22, 2017

View reviewed changes

jshier approved these changes Aug 22, 2017

View reviewed changes

cnoon approved these changes Aug 22, 2017

View reviewed changes

cnoon assigned jshier and cnoon Aug 22, 2017

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

ghost mentioned this pull request Aug 23, 2017

Add Jazzy Docs #2224

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Jazzy Docs #2250

Add Jazzy Docs #2250

ghost commented Aug 21, 2017

jshier left a comment

jshier Aug 21, 2017

jshier Aug 21, 2017

cnoon Aug 22, 2017

jshier Aug 22, 2017

jshier Aug 21, 2017

jshier Aug 21, 2017

cnoon commented Aug 22, 2017

cnoon left a comment

cnoon Aug 22, 2017

cnoon Aug 22, 2017

cnoon Aug 22, 2017

ghost commented Aug 22, 2017

cnoon left a comment

cnoon commented Aug 22, 2017

Add Jazzy Docs #2250

Add Jazzy Docs #2250

Conversation

ghost commented Aug 21, 2017

Issue Link 🔗

Goals ⚽

Implementation Details 🚧

Testing Details 🔍

Notes ⚠️

jshier left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cnoon commented Aug 22, 2017

cnoon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost commented Aug 22, 2017

cnoon left a comment

Choose a reason for hiding this comment

cnoon commented Aug 22, 2017