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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation #771

Closed
wants to merge 180 commits into
from

Conversation

Projects
None yet
9 participants
@ghuntley
Member

ghuntley commented Dec 8, 2014

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:

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

@ghuntley ghuntley referenced this pull request Dec 8, 2014

Closed

Fix reactiveui.net. #574

@ghuntley ghuntley self-assigned this Dec 8, 2014

@bennor

This comment has been minimized.

Show comment
Hide comment
@bennor

bennor Dec 8, 2014

👍 😸

bennor commented Dec 8, 2014

👍 😸

@d0ugal

This comment has been minimized.

Show comment
Hide comment
@d0ugal

d0ugal Dec 8, 2014

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

d0ugal commented Dec 8, 2014

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

This comment has been minimized.

Show comment
Hide comment
@bennor

bennor Dec 8, 2014

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.

bennor commented Dec 8, 2014

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

This comment has been minimized.

Show comment
Hide comment
@d0ugal

d0ugal Dec 15, 2014

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

d0ugal commented Dec 15, 2014

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

@shiftkey

This comment has been minimized.

Show comment
Hide comment
@shiftkey

shiftkey Dec 21, 2014

Contributor

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

Contributor

shiftkey commented Dec 21, 2014

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

This comment has been minimized.

Show comment
Hide comment
@d0ugal

d0ugal Dec 21, 2014

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

d0ugal commented Dec 21, 2014

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

docs/README.md
-## Sphinx Markup Constructs
+In the root of the `ReactiveUI` source directory:
+
+ $ make docs

This comment has been minimized.

@shiftkey

shiftkey Dec 22, 2014

Contributor

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'.

@shiftkey

shiftkey Dec 22, 2014

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@ghuntley

ghuntley Dec 22, 2014

Member

@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/

Member

ghuntley commented Dec 22, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@ghuntley

ghuntley Dec 22, 2014

Member

@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

Member

ghuntley commented Dec 22, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@ghuntley

ghuntley Jan 24, 2015

Member

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

Member

ghuntley commented Jan 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@RolandPheasant

RolandPheasant Jan 25, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@d0ugal

d0ugal Jan 25, 2015

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

d0ugal commented Jan 25, 2015

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

This comment has been minimized.

Show comment
Hide comment
@RolandPheasant

RolandPheasant Jan 25, 2015

Bit dumb of me not looking first!

Bit dumb of me not looking first!

@ghuntley ghuntley referenced this pull request Feb 9, 2015

Open

Good Examples #687

@ghuntley

This comment has been minimized.

Show comment
Hide comment
@ghuntley

ghuntley Feb 9, 2015

Member

Thanks @d0ugal for the heads up on Zeal/DashDocs. Definitely something we will do once rtfd/readthedocs.org#662 is resolved.

Documentation indeed is dull as ditchwater to write, have got three core people now in slack that are keen to knock off topics via the campfire (slack) to keep things interesting/momentum.

@RolandPheasant if notepad isn't your thing and you prefer to do code then that would be definitely welcome. What do you have in mind? Come chat in slack!

Member

ghuntley commented Feb 9, 2015

Thanks @d0ugal for the heads up on Zeal/DashDocs. Definitely something we will do once rtfd/readthedocs.org#662 is resolved.

Documentation indeed is dull as ditchwater to write, have got three core people now in slack that are keen to knock off topics via the campfire (slack) to keep things interesting/momentum.

@RolandPheasant if notepad isn't your thing and you prefer to do code then that would be definitely welcome. What do you have in mind? Come chat in slack!

@ghuntley ghuntley referenced this pull request in rtfd/readthedocs.org Feb 9, 2015

Closed

Intregration with Dash #662

0 of 4 tasks complete
@rdavisau

This comment has been minimized.

Show comment
Hide comment
@rdavisau

rdavisau Feb 9, 2015

Collaborator

Mapped:

  • legacy\basics\bindings.md -> concepts\binding.md
  • legacy\basics\data-binding.md -> binding\wpf.md
  • legacy\basics\reactive-list.md -> fundamentals\reactive-list.md
  • legacy\basics\create-derived-collection.md -> fundamentals\reactive-list-create-derived-collection.md
  • legacy\basics\dependency-resolution.md -> dependency-injection\splat.md needs to be updated for v6
  • legacy\basics\logging.md -> logging\splat.md
  • legacy\basics\logging.md -> logging\nlog.md tail of logging.md contained nlog info
  • legacy\basics\reactive-command.md -> concepts\reactive-command.md
  • legacy\basics\reactive-command-async.md -> commands\reactive-command-async.md
Collaborator

rdavisau commented on 2276bff Feb 9, 2015

Mapped:

  • legacy\basics\bindings.md -> concepts\binding.md
  • legacy\basics\data-binding.md -> binding\wpf.md
  • legacy\basics\reactive-list.md -> fundamentals\reactive-list.md
  • legacy\basics\create-derived-collection.md -> fundamentals\reactive-list-create-derived-collection.md
  • legacy\basics\dependency-resolution.md -> dependency-injection\splat.md needs to be updated for v6
  • legacy\basics\logging.md -> logging\splat.md
  • legacy\basics\logging.md -> logging\nlog.md tail of logging.md contained nlog info
  • legacy\basics\reactive-command.md -> concepts\reactive-command.md
  • legacy\basics\reactive-command-async.md -> commands\reactive-command-async.md
@flagbug

This comment has been minimized.

Show comment
Hide comment
@flagbug

flagbug May 11, 2016

Member

@ghuntley Do we still need this PR?

Member

flagbug commented May 11, 2016

@ghuntley Do we still need this PR?

@ghuntley

This comment has been minimized.

Show comment
Hide comment
@ghuntley

ghuntley May 11, 2016

Member

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

Member

ghuntley commented May 11, 2016

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

@ghuntley ghuntley closed this May 11, 2016

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