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 readme and docs #779

Merged
merged 3 commits into from
Sep 22, 2020
Merged

Conversation

noviluni
Copy link
Collaborator

@noviluni noviluni commented Sep 8, 2020

for: #723

What does this include?

  1. New README.md (moved from rst to markdown because the support is better in Github). I wrote it from scratch. Ideas are welcomed.
  2. Add the "read the docs" theme to the docs to get a result more similar to the real docs when building them locally.
  3. Update some configurations in the docs, including the new logo.
  4. Add some improvements to the docs:
    • move old "README.rst" as "introduction"
    • separate the "Supported locales" in a new section
    • improved the TOC tree
    • etc.
  5. Update the setup.py file and update the .travis.yml to use Python 3 to deploy the package.
  6. Removed the "Gitter" chat badge (is not maintained) and added the downloads badge.

To preview the README.md visit: https://github.com/scrapinghub/dateparser/blob/a542f25e51b6851d8bfd84e82b4c21c53457a716/README.md

To preview the docs: clone the project, run tox -e docs and check the index.htm file in ../.tox/docs/tmp/html.

Note that the settings need an extra cleanup, but I tried to avoid making too many changes in this PR. It should be fixed later.

On the other side, I don't know how to preview the pypi description.

@noviluni noviluni mentioned this pull request Sep 8, 2020
9 tasks
@noviluni noviluni changed the title Improve readme Improve readme and docs Sep 8, 2020
@Gallaecio
Copy link
Member

  1. New README.md (moved from rst to markdown because the support is better in Github)

Any example of a reStructuredText syntax that is not properly rendered in https://github.com/scrapinghub/dateparser and has a Markdown equivalent?

I tend to prefer reStructuredText because it allows things that Markdown doesn’t, such as those things you are now implementing in HTML within Markdown. I’m OK with switching to Markdown if Markdown is enough, but if the price is having HTML within Markdown, maybe it’s better to stay with reStructuredText.

@noviluni
Copy link
Collaborator Author

noviluni commented Sep 16, 2020

Hi @Gallaecio, I reverted it to use the rst format. Could you check it again?

I added the same HTML raw code, as I wasn't able to get the same result without it, any help on this will be appreciated.

On the other sider, opinions about the content, examples, etc. would be also appreciated.

Link to preview the current README.rst version: https://github.com/scrapinghub/dateparser/blob/08905be57af1a55e03f27098ea681d29b8cc98c8/README.rst

Thanks in advance! 🙂

@noviluni
Copy link
Collaborator Author

noviluni commented Sep 16, 2020

@Gallaecio I have just pushed a commit removing the HTML, but I can't get the expected result (text, image, etc. are not centered).

You can see here the version after removing the HTML code: https://github.com/scrapinghub/dateparser/blob/107e1b5026d1bd1a17694bfe237aa7b43b2e5b1b/README.rst

the version before (from my last comment): https://github.com/scrapinghub/dateparser/blob/08905be57af1a55e03f27098ea681d29b8cc98c8/README.rst

As you can see the HTML version has a better look and feel. Do you know how to fix it?

I personally think that rst is awesome for building documentation but unnecessary for READMEs as it's harder to edit (because it relies on spaces, etc.) and it's harder to learn. The old README was really bad but there weren't too many PRs to improve it and I think it's because of the format. It's ok to me to keep the rst format, but I want to get it to look like the HTML version. If not I think I prefer to keep at least the raw HTML.

@noviluni
Copy link
Collaborator Author

(FYI: I rechecked it and there is a bug in Github (that's the reason why I mentioned that the Markdown is better supported): github/markup#163). We should probably keep the HTML markup for the logo and the first section).

@Gallaecio
Copy link
Member

Well, if it’s only the alignment I would seriously consider just letting the images align left. But I’m OK with adding the raw HTML for that if you prefer; just add a comment (line starting with ..) linking to github/markup#163

@noviluni noviluni added this to the v1.0.0 milestone Sep 22, 2020
@noviluni noviluni merged commit eb194c4 into scrapinghub:master Sep 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants