Frontpage and Documentation overhaul

Moving forward
#1

A permanent homepage for Sanic on https://sanicframework.org is coming.

I started a new repo that uses Docsify to overhaul the documentation. My proposal is to make the main homepage this new user guide. It should operate more as a tutorial style guide with plenty of examples and use cases.

It follows some of the existing content, but I am trying to fill in some of the missing gaps, and to organize it more intuitively. One thing the current docs lack is a good flow. If you are not already familiar with them, it is hard to find information.

So, what about Sphinx and RTD? I want to remove all of the existing .rst pages in the main repo, and instead only focus that on docstring documentation of the API. I have a branch that I am holding off on a PR until after streaming is merged.

Let me know if you have any thoughts or would like to contribute. Suggestions for additional articles in the “How to” section are encouraged.

Also, see older thread.

2 Likes
#2

I highly recommend checking out Vuepress https://vuepress.vuejs.org/ if you are starting from scratch. I have used docsify for docs in the past but it is not very SEO friendly since the docs are only rendered on the client side. (Translation: Google won’t index anything on the site. Example: I won’t be able to Google sanic request to quickly go to what’s inside that object anymore)

Vuepress is rendered on-the-fly during development (so it’s the same client-side rendering for dev) but you can deploy the site as static files, which makes it very SEO friendly.

I know that docsify does have a plan to add static site generation but that issue was added in 2017 and it’s still open right now: Generate static HTML site (static site generation, SSG) · Issue #136 · docsifyjs/docsify · GitHub

There are other flexibility in Vuepress also and I have been happy with it.

Docsify docs can easily be ported to Vuepress since it uses similar Markdown and similar folder structure. Structurally, the main difference between the two is how to setup internationalization and nav elements.

2021 Release Managers and Updates
#3

Thanks for the heads up. SEO was on my list to look into, glad to have that information.

1 Like
#4

I took your advice. Looks like there are some great plugins available. With your vuepress expertise, I would welcome any more thoughts or contributions you might have to get it rolling.

1 Like
#5

hi @ahopkins I am very excited that Sanic’s document will usher in a new change.
I have already fork sanic-guide project. And I hope there will be more Chinese developer to know and use Sanic Framework. So I have started my translation work now.

I hope I can make a contribution to the forums.

Although my English is not very good, at least it makes the document look smoother than Google translation.

Can the community reserve an entrance for Chinese documents? We will be very grateful.

If this is allowed, I will do my best to maintain this Chinese document in the future until you find a professional translator.

Looking forward to your reply!

image
image1920×947 84.7 KB

#6

This is awesome. I opened an issue for this. There are some useful plug-ins for translation support.

#7

I am very glad to hear from you.

But I don’t agree with using translation plug-ins because of vuepress supports multiple languages.

I think we should arrange the files under src/guide in the following like this:

src/guide
├─advanced
├─basics
├─best-practices
├─deployment
├─how-to
└─zh    # Chinese document folder
    ├─advanced
    ├─basics
    ├─best-practices
    ├─deployment
    └─how-to

I will translate these documents and place them as new files in src/guide/zh folder

After that, we just need to modify .vuepress/config.js to add some config in sidebar:

    sidebar: {
      "/guide/zh/": [{
          title: "概览",
          sidebarDepth: 1,
          children: ["/guide/zh/", "/guide/zh/getting-started.md"],
        },
     ...
      ],
      "/guide/": [{
          title: "General",
          sidebarDepth: 1,
          children: ["/guide/", "/guide/getting-started.md"],
        },
       ...
      ]
    }

Maybe you will ask what to do if the document is updated. Don’t worry. I think that since we are going to make a formal document, this document will definitely not be changed frequently. It is enough for me to modify it manually with minor changes.

Why should I insist on this deployment?

Because I think if you use translation plug-in, what’s the difference between it and Google Translation?

In order to ensure the accuracy of expressing meaning and the fluency of documents,

I think it’s better to support multiple languages in my way.

What do you think?

I just thought about it carefully, maybe I misunderstood what you said.

I have always thought that you want to implement localization operations by using third-party translation plugins, but after I carefully figured it out, I think you are referring to the use of vuepress to implement multilingual sites.

I am sorry that I said the above without thinking carefully.

Let’s implement sanic’s multi-language support together. Come on!

Now I have completed the multilingual support of menu and homepage, and I am still translating the document part. When I finish translating, I will do PR operation.

image
image1920×947 58.9 KB

#8

:sunglasses: Yes, this is what I meant.

There may be some pain keeping in sync the next couple months because there is still a lot to add. After initial launch, we should probably add some system around PRs to have your approval and additional commits when there are changes. So, if someone adds a new section or makes a change, you can push a commit as well.

The same for any other languages we decide to suppoort.

#9

I can’t agree with you more.

Let us work hard to make the community better

1 Like
#10

Great! I have translated some of theses .md files, how to participate in this project? Did you have a Github repository?

#11

Hope we don’t already translate the same document. :upside_down_face:

#12
#13

This is my translation project. Some contents are not translated well and need polishing. You can check whether there are duplicate documents first.
https://github.com/miss85246/sanic-guide

#14

@ahopkins @misss85246 Thanks ahopkins, I had forked the repo. should we have a translation branch so that others can fork and PR?

#15

So did you read the documents I translated? Is there duplicated with yours ？

#16

Yes. I will add you both to the repo so you can more easily push changes. @ZinkLu what is your GitHub username?

#17

No, I translated backwards . I have done class-based-views.md and part of proxy-headers.md. I will push to the branch later.

#18

I have replied under the issue. Language support · Issue #4 · sanic-org/sanic-guide · GitHub

#19

well, I have finished the translation of class-based-view too, we can see how to translate more smoothly.

#20

OK :ok_hand:, Let’s more 信达雅 if we could :stuck_out_tongue_winking_eye: