search

lingui / js-lingui

🌍 📖 A readable, automated, and optimized (3 kb) internationalization for JavaScript
https://lingui.dev
MIT License
4.49k stars 378 forks source link

Create new, structured documentation #17

Closed tricoder42 closed 6 years ago

tricoder42 commented 7 years ago

⚠️ Work in progress

Documentation

Website

Content

Tutorials

References

Guides

Discussions

kirillku commented 6 years ago

Thank you for a nice react tutorial. But have some troubles using cli tool. Could you add to lingui-cli section, what is _build folder, why it is created and should it be committed?

tricoder42 commented 6 years ago

@kirillku Absolutely, good point 👍

In short:

I'll push updated docs soon.

Teloah commented 6 years ago

Could you please also add a testing tutorial? Something of like this for React Intl: https://github.com/yahoo/react-intl/wiki/Testing-with-React-Intl I'm mostly interested in testing using Jest and Enzyme.

tricoder42 commented 6 years ago

Good point!

For now take a look at test cases for example project, especially Children.test.js shows the most common patterns.

vonovak commented 6 years ago

@tricoder42 I feel like the documentation is now the biggest barrier for entry (I miss a non-react tutorial for instance), even though many things can be found in the source or in tests. What I kind of miss in the docs is having an easy way to edit the docs - like there is for example with react native and many others. I'd be up to creating a short doc for using js-lingui with react native. How does one contribute to the docs?

tricoder42 commented 6 years ago

@vonovak I'm gonna update contributor guide. Short answer:

  1. Documentation uses Sphinx and reStructuredText. It's inside docs directory.
  2. To setup python virtualenv, run pipenv install inside docs
  3. Run make html to build docs
  4. After everychange, run make html to rebuild the docs. Incremental builds are much faster than first one
vonovak commented 6 years ago

@tricoder42 so I finally wanted to write up the docs for vanilla JS usage because I think the project needs it so much. I never worked with python and am not familiar with the environment. I have Python 2.7.10.

I followed the instructions you gave and run pipenv install that went well. Then make html failed with /usr/bin/python: No module named sphinx. Seems like pip is the way to install sphinx it, but I first needed to install pip which I did through easy_install which agin I found somewhere on SO probably.

I ended up with 

...
matplotlib 1.3.1 requires nose, which is not installed.
matplotlib 1.3.1 requires tornado, which is not installed.
Installing collected packages: imagesize, six, Pygments, sphinxcontrib-websupport, alabaster, snowballstemmer, docutils, typing, babel, certifi, chardet, idna, urllib3, requests, pyparsing, packaging, MarkupSafe, Jinja2, sphinx
  Found existing installation: six 1.4.1
Cannot uninstall 'six'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall.

at which point I gave up.

Can you please update the contributor guide with proper instructions on how to contribute to the docs? That would be great, thanks. Or go with something that is simple to get running https://github.com/facebook/Docusaurus and makes it very easy for anybody to contribute to the docs.

tricoder42 commented 6 years ago

@vonovak Sorry, I forgot to mention pipenv run. Please try pipenv run make html inside docs directory. Once you have it (there might be few warnings), simply open docs/_build/html/index.html in your browser.

I would really like to use reStructuredText. Markdown is really nice and simple for small documents, but I like custom extensions to reStructuredText (e.g cli commands, components, etc). I could prepare docker image, but thanks to pipenv it's now very easy to install all dependencies and virtual environment. I just need to update contributing guide with correct steps.

Please let me know if it works for you!

vonovak commented 6 years ago

@tricoder42 thanks, that works: https://github.com/lingui/js-lingui/pull/216

tricoder42 commented 6 years ago

@Teloah There's now a testing guide

tricoder42 commented 6 years ago

Alright, I'm finally closing this one, because documentation is mostly complete. If you still feel there's something missing, please let me know!