From 4c00cb8c8b8ac50d3e3364f928511ae238bf3164 Mon Sep 17 00:00:00 2001 From: ines Date: Sun, 28 May 2017 18:45:49 +0200 Subject: [PATCH] Update 101 and add community/FAQ and table of contents --- website/docs/usage/_data.json | 3 +- website/docs/usage/spacy-101.jade | 174 +++++++++++++++++++++++++++++- 2 files changed, 173 insertions(+), 4 deletions(-) diff --git a/website/docs/usage/_data.json b/website/docs/usage/_data.json index 59057b0bb..79d0b28f1 100644 --- a/website/docs/usage/_data.json +++ b/website/docs/usage/_data.json @@ -43,7 +43,8 @@ "spacy-101": { "title": "spaCy 101", - "next": "lightning-tour" + "next": "lightning-tour", + "quickstart": true }, "lightning-tour": { diff --git a/website/docs/usage/spacy-101.jade b/website/docs/usage/spacy-101.jade index 72774daf3..49ba1e64c 100644 --- a/website/docs/usage/spacy-101.jade +++ b/website/docs/usage/spacy-101.jade @@ -2,9 +2,34 @@ include ../../_includes/_mixins ++h(2, "whats-spacy") What's spaCy? + ++grid + +grid-col("half") + + +grid-col("half") + +infobox + +label.o-block-small Table of contents + +list("numbers").u-text-small.o-no-block + +item #[+a("#features") Features] + +item #[+a("#annotations") Linguistic annotations] + +item #[+a("#annotations-token") Tokenization] + +item #[+a("#annotations-pos-deps") POS tags and dependencies] + +item #[+a("#annotations-ner") Named entities] + +item #[+a("#vectors-similarity") Word vectos and similarity] + +item #[+a("#pipelines") Pipelines] + +item #[+a("#vocab") Vocab, hashes and lexemes] + +item #[+a("#serialization") Serialization] + +item #[+a("#training") Training] + +item #[+a("#architecture") Architecture] + +item #[+a("#community") Community & FAQ] + +h(2, "features") Features -+under-construction +p + | Across the documentations, you'll come across mentions of spaCy's + | features and capabilities. Some of them refer to linguistic concepts, + | while others are related to more general machine learning functionality. +aside | If one of spaCy's functionalities #[strong needs a model], it means that @@ -219,10 +244,12 @@ include _spacy-101/_training +row +cell #[code Morphology] +cell + | Assign linguistic features like lemmas, noun case, verb tense etc. + | based on the word and its part-of-speech tag. +row +cell #[+api("stringstore") #[code StringStore]] - +cell Map strings to and from integer IDs. + +cell Map strings to and from hash values. +row +row @@ -259,7 +286,7 @@ include _spacy-101/_training +table(["Name", "Description"]) +row +cell #[+api("binder") #[code Binder]] - +cell + +cell Container class for serializing collections of #[code Doc] objects. +row +cell #[+api("goldparse") #[code GoldParse]] @@ -270,3 +297,144 @@ include _spacy-101/_training +cell | An annotated corpus, using the JSON file format. Manages | annotations for tagging, dependency parsing and NER. + ++h(2, "community") Community & FAQ + +p + | We're very happy to see the spaCy community grow and include a mix of + | people from all kinds of different backgrounds – computational + | linguistics, data science, deep learning and research. If you'd like to + | get involved, below are some answers to the most important questions and + | resources for further reading. + ++h(3, "faq-help-code") Help, my code isn't working! + +p + | Bugs suck, and we're doing our best to continuously improve the tests + | and fix bugs as soon as possible. Before you submit an issue, do a + | quick search and check if the problem has already been reported. If + | you're having installation or loading problems, make sure to also check + | out the #[+a("/docs/usage#troubleshooting") troubleshooting guide]. Help + | with spaCy is available via the following platforms: + ++aside("How do I know if something is a bug?") + | Of course, it's always hard to know for sure, so don't worry – we're not + | going to be mad if a bug report turns out to be a typo in your + | code. As a simple rule, any C-level error without a Python traceback, + | like a #[strong segmentation fault] or #[strong memory error], + | is #[strong always] a spaCy bug.#[br]#[br] + + | Because models are statistical, their performance will never be + | #[em perfect]. However, if you come across + | #[strong patterns that might indicate an underlying issue], please do + | file a report. Similarly, we also care about behaviours that + | #[strong contradict our docs]. + ++table(["Platform", "Purpose"]) + +row + +cell #[+a("https://stackoverflow.com/questions/tagged/spacy") StackOverflow] + +cell + | #[strong Usage questions] and everything related to problems with + | your specific code. The StackOverflow community is much larger + | than ours, so if your problem can be solved by others, you'll + | receive help much quicker. + + +row + +cell #[+a("https://gitter.im/" + SOCIAL.gitter) Gitter chat] + +cell + | #[strong General discussion] about spaCy, meeting other community + | members and exchanging #[strong tips, tricks and best practices]. + | If we're working on experimental models and features, we usually + | share them on Gitter first. + + +row + +cell #[+a(gh("spaCy") + "/issues") GitHub issue tracker] + +cell + | #[strong Bug reports] and #[strong improvement suggestions], i.e. + | everything that's likely spaCy's fault. This also includes + | problems with the models beyond statistical imprecisions, like + | patterns that point to a bug. + ++infobox + | Please understand that we won't be able to provide individual support via + | email. We also believe that help is much more valuable if it's shared + | publicly, so that #[strong more people can benefit from it]. If you come + | across an issue and you think you might be able to help, consider posting + | a quick update with your solution. No matter how simple, it can easily + | save someone a lot of time and headache – and the next time you need help, + | they might repay the favour. + ++h(3, "faq-contributing") How can I contribute to spaCy? + +p + | You don't have to be an NLP expert or Python pro to contribute, and we're + | happy to help you get started. If you're new to spaCy, a good place to + | start is the + | #[+a(gh("spaCy") + '/issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted+%28easy%29"') #[code help wanted (easy)] label] + | on GitHub, which we use to tag bugs and feature requests that are easy + | and self-contained. We also appreciate contributions to the docs – whether + | it's fixing a typo, improving an example or adding additional explanations. + +p + | Another way of getting involved is to help us improve the + | #[+a("/docs/usage/adding-languages#language-data") language data] – + | especially if you happen to speak one of the languages currently in + | #[+a("/docs/api/language-models#alpha-support") alpha support]. Even + | adding simple tokenizer exceptions, stop words or lemmatizer data + | can make a big difference. It will also make it easier for us to provide + | a statistical model for the language in the future. Submitting a test + | that documents a bug or performance issue, or covers functionality that's + | especially important for your application is also very helpful. This way, + | you'll also make sure we never accidentally introduce regressions to the + | parts of the library that you care about the most. + +p + strong + | For more details on the types of contributions we're looking for, the + | code conventions and other useful tips, make sure to check out the + | #[+a(gh("spaCy", "CONTRIBUTING.md")) contributing guidelines]. + ++infobox("Code of Conduct") + | spaCy adheres to the + | #[+a("http://contributor-covenant.org/version/1/4/") Contributor Covenant Code of Conduct]. + | By participating, you are expected to uphold this code. + ++h(3, "faq-project-with-spacy") + | I've built something cool with spaCy – how can I get the word out? + +p + | First, congrats – we'd love to check it out! When you share your + | project on Twitter, don't forget to tag + | #[+a("https://twitter.com/" + SOCIAL.twitter) @#{SOCIAL.twitter}] so we + | don't miss it. If you think your project would be a good fit for the + | #[+a("/docs/usage/showcase") showcase], #[strong feel free to submit it!] + | Tutorials are also incredibly valuable to other users and a great way to + | get exposure. So we strongly encourage #[strong writing up your experiences], + | or sharing your code and some tips and tricks on your blog. Since our + | website is open-source, you can add your project or tutorial by making a + | pull request on GitHub. + ++aside("Contributing to spacy.io") + | All showcase and tutorial links are stored in a + | #[+a(gh("spaCy", "website/docs/usage/_data.json")) JSON file], so you + | won't even have to edit any markup. For more info on how to submit + | your project, see the + | #[+a(gh("spaCy", "CONTRIBUTING.md#submitting-a-project-to-the-showcase")) contributing guidelines] + | and our #[+a(gh("spaCy", "website")) website docs]. + +p + | If you would like to use the spaCy logo on your site, please get in touch + | and ask us first. However, if you want to show support and tell others + | that your project is using spaCy, you can grab one of our + | #[strong spaCy badges] here: + +- SPACY_BADGES = ["built%20with-spaCy-09a3d5.svg", "made%20with%20❤%20and-spaCy-09a3d5.svg", "spaCy-v2-09a3d5.svg"] ++quickstart([{id: "badge", input_style: "check", options: SPACY_BADGES.map(function(badge, i) { return {id: i, title: "", checked: (i == 0) ? true : false}}) }], false, false, true) + .c-code-block(data-qs-results) + for badge, i in SPACY_BADGES + - var url = "https://img.shields.io/badge/" + badge + +code(false, "text", "star").o-no-block(data-qs-badge=i)=url + +code(false, "text", "code").o-no-block(data-qs-badge=i). + <a href="#{SITE_URL}"><img src="#{url}" height="20"></a> + +code(false, "text", "markdown").o-no-block(data-qs-badge=i). + [![spaCy](#{url})](#{SITE_URL})