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.

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

Improve the getting started docs #4676

Merged
merged 7 commits into from Oct 5, 2018

Conversation

@davidfischer
Copy link
Contributor

@davidfischer davidfischer commented Sep 28, 2018

  • Adds an introductory few paragraphs to docs/index page to explain the value proposition of Read the Docs. The goal here is to answer the "Why Read the Docs" question.
  • Breaks the getting started guide into 3 docs
    • getting started with Sphinx
    • getting started with MkDocs (this is brand new)
    • importing your documentation
  • In the getting started with X guides, I briefly explain the benefits/trade-offs of using Sphinx/MkDocs
  • Puts "connecting your account" (to GitHub, Bitbucket, GitLab) into a separate doc rather than in the getting started guide. This won't be as necessary going forward as more people choose to sign up with GitHub, etc.
  • In the toctree, moves:
    • the "about Read the Docs" section below "Feature documentation"
    • puts the "Design" section into the developer documentation

After merging

Create a redirect in the Read the Docs project dashboard for the "docs" project from getting-started.html -> intro/getting-started-with-sphinx.html.

Notes

I would like to put full sentence/paragraph descriptions on different sections (eg. User documentation, Feature documentation, About Read the Docs, etc.), but there isn't a great way to do this. I still think we should do it to explain the differences between those various sections. Currently the best path I have for that is similar to what I did with "First steps" which is to make the toctree hidden and then also have duplicate links to the documents.

What are peoples' thoughts on having more screenshots in our docs? I put one in the import guide but I could easily create a lot more. I think especially in getting started guides, these are very reassuring and show people they are doing the right thing in the right place.

Fixes #4648

@davidfischer davidfischer requested a review from Sep 28, 2018
Copy link
Member

@stsewd stsewd left a comment

I like these new docs! Shouldn't we mention the configuration part here? Like using a configuration file or the web admin.

Loading


.. sourcecode:: bash

$ pip install mkdocs
Copy link
Member

@stsewd stsewd Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how this is rendered, but maybe dropping the $ makes easier to copy/paste

Loading

Copy link
Contributor Author

@davidfischer davidfischer Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't really render any different from the existing getting started guide. The only difference is that any shell builtins (eg. echo, cd, etc.) are syntax highlighted. It also is more explicit.

There's a few places in our docs that use the pattern of $ shellcommand so I'm hesitant to change it without changing it everywhere.

Loading

Copy link
Member

@ericholscher ericholscher Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I generally dislike the $ for the reason mentioned (hard to copy/paste), but don't feel strongly.

Loading

Copy link
Contributor Author

@davidfischer davidfischer Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added an issue for it: #4698

Loading

Open up http://127.0.0.1:8000/ in your web browser to see your documentation.
You can make changes to your Markdown files and your docs will automatically rebuild.

Once you have your documentation in a public repository such GitHub, Bitbucket, or GitLab,
Copy link
Member

@stsewd stsewd Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not an English guy, but shouldn't be such as?

Loading

Copy link
Contributor Author

@davidfischer davidfischer Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes it should. Thanks

Loading

.. sourcecode:: bash

$ cd /path/to/project
$ mkdir docs
Copy link
Member

@stsewd stsewd Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't mention this on the MkDocs guide

Loading

Copy link
Contributor Author

@davidfischer davidfischer Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. Running mkdocs new . creates mkdocs.yml at the root (not in docs/) and docs/index.md.

Loading

Copy link
Contributor Author

@davidfischer davidfischer Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also creates the docs directory if it doesn't exist.

Loading


.. sourcecode:: bash

$ make html
Copy link
Member

@stsewd stsewd Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mentioning that this is only valid for unix like systems?

Loading

Copy link
Contributor Author

@davidfischer davidfischer Sep 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Windows, I believe it works as-is because Sphinx will create a make.bat file.

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Sep 28, 2018

Shouldn't we mention the configuration part here? Like using a configuration file or the web admin.

I think that's a great idea.

Where do you think it should go? Perhaps just a sentence or two in "Importing Your Documentation >> Building your documentation" and it links to the Yaml config docs?

I also think the Yaml config docs should be linked from the builds docs.

Loading

@stsewd
Copy link
Member

@stsewd stsewd commented Sep 28, 2018

I also think the Yaml config docs should be linked from the builds docs.

Definitely, that's a good place

Where do you think it should go? Perhaps just a sentence or two in "Importing Your Documentation >> Building your documentation" and it links to the Yaml config docs?

That's a good question p: not sure, maybe it makes sense on an early step? Looks like an intermediate step between creating the documentation and importing/building it on rtd.

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Sep 28, 2018

If you don't have a strong opinion, I lean toward putting it in "Importing Your Documentation >> Building your documentation". I think that because many projects (especially simple ones) won't need it and I want to keep the getting started guide short and simple.

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Sep 28, 2018

I linked to the Yaml config on "Importing Your Documentation". The builds page needs a bit more work and is a little out of scope for this PR. I created #4679 to handle it.

Loading

* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials

To connect your account, go to your *Settings* dashboard and select *Connected
Services*. From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
Copy link
Member

@ericholscher ericholscher Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe you can also just "login" with the accounts and it will connect them. This is probably the most explicit way of documenting doing it though 👍

Loading

Copy link
Contributor Author

@davidfischer davidfischer Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Signing up will connect them. I'll make that a bit more clear.

Loading


.. sourcecode:: bash

$ pip install mkdocs
Copy link
Member

@ericholscher ericholscher Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I generally dislike the $ for the reason mentioned (hard to copy/paste), but don't feel strongly.

Loading

Copy link
Member

@ericholscher ericholscher left a comment

Looks great.

What are peoples' thoughts on having more screenshots in our docs? I put one in the import guide but I could easily create a lot more. I think especially in getting started guides, these are very reassuring and show people they are doing the right thing in the right place.

I like screenshots. We don't have a great way of managing them, but I'm +1 on having them, especially in tutorial/intro docs.

Loading

@@ -105,6 +124,8 @@ Information about development is also available:
i18n
issue-labels
security
design
RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
Copy link
Member

@ericholscher ericholscher Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should really make this a subproject and have a nicer integration between the two sets of docs.

Loading

Copy link
Contributor Author

@davidfischer davidfischer Oct 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you go into a little more detail about what you mean by this?

Loading

Copy link
Member

@ericholscher ericholscher Oct 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should make it a subproject and use some of our fancier features that we build for users on our own stuff.

Loading

Copy link
Contributor

@agjohnson agjohnson Oct 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i started on this path to restructure all of our docs -- add all subprojects/translations and break up community user docs, community developer docs, and commercial docs. probably part of a larger thing that we should dog food on the .com

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Oct 1, 2018

I like screenshots. We don't have a great way of managing them, but I'm +1 on having them, especially in tutorial/intro docs.

I added screenshots. I moved the images around (under _static) and re-enabled html_static_path so that I could create hyperlinks to the images themselves.

Loading

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Oct 1, 2018

The lint errors are due to search stuff, not these docs.

Loading

Copy link
Contributor

@agjohnson agjohnson left a comment

Content looks great, just noted a couple small changes that aren't super important.

A larger issue is that content here does not reflect our commercial hosting, but we don't have a good pattern for this yet anyways. We'll need to revisit this to make the necessary changes there (no manual import, you must be repo admin to import, etc, etc)

Loading

docs/intro/getting-started-with-mkdocs.rst Show resolved Hide resolved
Loading
and many projects large and small use Sphinx
including the Django project and the Python programming language.
However, Read the Docs also supports :doc:`MkDocs </intro/getting-started-with-mkdocs>`,
another tool for writing and building documentation.
Copy link
Contributor

@agjohnson agjohnson Oct 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we necessarily want to point out mkdocs here, if anything because we're not giving a reason for the user to consider mkdocs with this sentence. I think our position is that the author would be better off with Sphinx and RTD anyways, due to the lack of feature parity on mkdocs. I'd be 👍 on dropping the mkdocs callout here.

Loading

Copy link
Contributor Author

@davidfischer davidfischer Oct 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed it. We could also discuss some of the differences like lack of PDF/e-reader support in mkdocs but I don't know if it is necessary.

Loading

Copy link
Contributor

@agjohnson agjohnson Oct 3, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, yeah. Perhaps a good doc to have in general, but i'd agree, not necessary for getting started PR here.

Loading

@davidfischer davidfischer merged commit d3d922d into master Oct 5, 2018
1 check passed
Loading
@davidfischer davidfischer deleted the davidfischer/docs-getting-started-improvements branch Oct 5, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants