Documentation

[ghuntley]

Introduction

It's time for versioned documentation and better samples!

If you want to help out with this please comment on this issue and I'll add you as a contributor to my personal repository.

See following for inspiration:

• http://jacobian.org/writing/what-to-write/
• http://jacobian.org/writing/technical-style/
• http://jacobian.org/writing/editors/

See following for collection of projects with beautiful documentation: https://github.com/PharkMillups/beautiful-docs for inspiration

Operations:

• Use Readthedocs.org to automatically build ReactiveUI documentation as it supports versioned documentation via branches.
• Resolve Multi-page documentaion does not work on Windows mkdocs/mkdocs#238
• CNAME created for docs.reactiveui.net pointed towards readthedocs.
• Determine what to use and how to automatically build class documentation.
• Documentation Theme
• Structure of documentation defined.
• Migrate existing docs/* across.
• Clean existing docs/* to drop all stale Rx4 and Rx5 references.

Ideas for samples?

• Sub-classing of UserError
• Handling subclassed UserError Inline or via Global Registration
• Using IRecoveryCommand and RecoveryOptionResult? "I have a LoginCommand which internally does an http request to my server. Depending on the Response (200, 401, <5xx and timeouts>), I'd like to either (200 -> dismiss login dialog / 401 -> show "bad credentials" alert message ("OK") / <5xx and timenouts> -> show "Error" alert message ("Cancel", "Retry"). I thought throwing an UserError for 401 and <5xx and timenouts> with a retry command would make sense, but I'm not sure how to use the built-in Recovery stuff in ReactiveUI."
• General Navigation - WPF and WinForms
• Xamarin Forms - Navigation, Binding on all platforms.
• Suspension Host on all platforms
• Service Location
• Caching using Akavache
• Integrating ModernHTTPClient with Fusillade and Refit
• Using Splat/IBitmap x-platform within the PCL and value converters on each platform to display images.
• Reactive Dialogs. PCL Dialog Service -> iOS/Android impl which is observable based on which button pressed. Yes, No, Cancel.
• Example of a custom RoutedViewHost (say iOS tab menu or navigation stack)

[bennor]

👍 😸

[d0ugal]

Nice. Let me know if there is anything I can do to help from the MkDocs/ReadTheDocs side - other than the issue linked above (which is almost solved now).

[bennor]

I'm very keen to help out, but my knowledge of RxUI is fairly limited at this stage.

Some stuff I might be able to help out with:

• Theming: I'm not a designer, but I can CSS and I know what's ugly and what's isn't. If anyone knows a real designer who wants to help, I could do the grunt work to turn PSD into HTMLs. Otherwise, I can just have a crack at coming up with something simple and clean myself.
• I don't have the technical knowledge to write the docs from scratch, but I'd be happy to translate from programmer to English.
• I know my way around refit well enough to maybe put together a sample for refit + fusillade + modernhttpclient, but I imagine I'll need some tips on how exactly to tie this into RxUI.

What I would like to see in the docs:

• As someone who is very new to RxUI, I think an end-to-end tutorial of a simple app would be really valuable. (Something like the angular tutorial, ideally with each step as a branch in a git repo.)
• This is kind of similar, but it would be great to see the documentation logically organized: starting with the absolute basics and building from there to more advanced stuff, so it reads kind of like a book rather than a collection of unrelated articles.

[d0ugal]

FYI mkdocs/mkdocs#238 is now resolved, we hope to do a release soon.

[shiftkey]

If you want to help out with this please comment on this issue and I'll add you as a contributor to my personal repository.

/me waves

[d0ugal]

Can we use commit messages that mean something? Kinda hard to see what is going on.

[shiftkey]

Any tips for testing out these docs locally?

This is what I get when running from the root of the repository:

make docs
make: Nothing to be done for `docs'.

[ghuntley]

@bennor previously wrote:

I'm very keen to help out, but my knowledge of RxUI is fairly limited at this stage.

Perfect. Edit the docs with any snippets of info you pick up along the way - even chatlogs from slack are acceptable. Check out http://docs.reactiveui.net/en/latest/contributing

Theming: I'm not a designer, but I can CSS and I know what's ugly and what's isn't. If anyone knows a real designer who wants to help, I could do the grunt work to turn PSD into HTMLs. Otherwise, I can just have a crack at coming up with something simple and clean myself.

Not needed yet; let's foucs on structure and content.

I don't have the technical knowledge to write the docs from scratch, but I'd be happy to translate from programmer to English.

That would be helpful :-)

I know my way around refit well enough to maybe put together a sample for refit + fusillade + modernhttpclient, but I imagine I'll need some tips on how exactly to tie this into RxUI.

I'll do this w/ EndlessCats.

What I would like to see in the docs:
As someone who is very new to RxUI, I think an end-to-end tutorial of a simple app would be really valuable. (Something like the angular tutorial, ideally with each step as a branch in a git repo.)

Handled by a SideWaffle template plus documentation. Don't want the first couple pages of instructions to be right click right click.

This is kind of similar, but it would be great to see the documentation logically organized: starting with the absolute basics and building from there to more advanced stuff, so it reads kind of like a book rather than a collection of unrelated articles.

Completely agree and that's the direction we are going for -> see http://jacobian.org/writing/what-to-write/

[ghuntley]

@d0ugal wrote:

Can we use commit messages that mean something? Kinda hard to see what is going on.

Have rebased the repository, useful commits from this place onwards and it is now ready to take on contributors.

@shiftkey @bennor and @mteper you have been added as contributors on my repo.

The preferred way to contribute for this pull-request is to either use the github markdown editor directly on the file within my repo or commit/push directly into my repo at https://github.com/ghuntley/reactiveui/tree/readthedocs

The repo has been configured with a webhook to automatically rebuild http://docs.reactiveui.net upon checkin.

Instructions for how to get up and running locally are available at https://github.com/ghuntley/ReactiveUI/tree/readthedocs/docs

[ghuntley]

@RolandPheasant have granted you read/write permission to https://github.com/ghuntley/ReactiveUI/tree/readthedocs/docs . See previous comment to explain how to use this.

[RolandPheasant]

I am very tempted to contribute here. But being as writing documentation is as dull as ditch water perhaps we need to create a cross platform document viewer first. Of course it would be written using ReactiveUI.

[d0ugal]

What you need is a Mardown viewer, about a million of these already exist.

There are also some nice docs viewers like: http://zealdocs.org

[RolandPheasant]

Bit dumb of me not looking first!

[flagbug]

@ghuntley Do we still need this PR?

[ghuntley]

🔥 It can be closed. Everything is located at http://docs.reactiveui.net now - send corrections to https://github.com/reactiveui/documentation via PR.