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

Set up a documentation site #1138

Closed
epicfaace opened this issue Jan 19, 2019 · 5 comments
Closed

Set up a documentation site #1138

epicfaace opened this issue Jan 19, 2019 · 5 comments
Assignees
@glasserc

Comments

@epicfaace
Copy link
Member

We should transition away from using a very long README.md for docs and generate a documentation site instead.

I was thinking https://readthedocs.org/ -- any other suggestions? @glasserc @edi9999
@edi9999
Copy link
Collaborator

edi9999 commented Jan 19, 2019

+1 for readthedocs, it provides clean documentation, with also documentation per version, PDF export.

One example on another project I maintain : https://docxtemplater.readthedocs.io/en/latest/

@epicfaace
Copy link
Member Author

I don't have admin access to this repo, so @glasserc you may need to set it up with readthedocs.

epicfaace added a commit that referenced this issue Jan 21, 2019
@epicfaace
doc: organize docs into separate files #1138
7e74bb6
epicfaace added a commit that referenced this issue Jan 21, 2019
@epicfaace
docs: remove docs from README and link to readthedocs #1138
f62cfc4
KeroVieux added a commit to KeroVieux/react-jsonschema-form that referenced this issue Jan 25, 2019
@KeroVieux
Merge branch 'master' of github.com:KeroVieux/react-jsonschema-form
7108bf3 
* 'master' of github.com:KeroVieux/react-jsonschema-form:
  updated
  replace submit button paragraph tag with div (rjsf-team#766)
  Fixes rjsf-team#824 (rjsf-team#1147)
  Fix bug where matching anyOf branch is not selected correctly (rjsf-team#1129)
  Document a gotcha with `additionalProperties` (rjsf-team#1149)
  doc: add permalinks and fix internal hyperlinks in documentation
  doc: add doc build instructions, update PR/issue templates with doc links
  Add onBlur and onFocus events for radio and checkbox widgets (rjsf-team#1143)
  add ui:help tips (rjsf-team#1145)
  doc: fix browserstack logo size
  docs: remove docs from README and link to readthedocs rjsf-team#1138
  doc: organize docs into separate files rjsf-team#1138
  doc: add browserstack logo rjsf-team#990
  Add test and update documentation for using anyOf inside array items (rjsf-team#1131)

# Conflicts:
#	src/components/Form.js
@pubudu-ranasinghe
Copy link

Please consider bringing back the docs in readme. The separate site makes it extremely difficult to navigate. Having everything in one page with the ToC made it so much easier to quickly navigate and find the references.
IMO the docs are not large enough to warrant a different website.

@epicfaace
Copy link
Member Author

@pubudu-ranasinghe the docs are really long, it was getting unwieldy to keep it in a README.

Could you explain a bit more about what difficulties you are facing? The categories on the sidebar may definitely need to be better reorganized, but I had just copied over the same title from the README for the time being when doing the docs. The docs site does have a "Search..." feature -- does that not work for your navigation/references need?

@pubudu-ranasinghe
Copy link

I guess you are right. It is too long. In the readme I knew where everything was(almost from muscle memory)
For example,
One tricky thing I always come back to is how to use oneOf It was somewhat difficult to find. I have to come to the repo. Scroll down to find the doc site link. Go there and find the definitions.

But this is unavoidable I guess.

@snyk-bot snyk-bot mentioned this issue Jan 30, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@glasserc glasserc

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@glasserc @epicfaace @edi9999 @pubudu-ranasinghe