docs : Cleaned up documentation #861

yash2189 · 2020-10-26T17:45:36Z

Fixes #789

Description:

Previously , the information was scattered among different files. This PR organizes all the contents for the development documentation , contribution files under separate sections so that a better understanding of the entire project can be obtained for newcomers or the existing contributors for this project.

What has been added ?

Organized file sections under docs . Please find the changes here
Separate development docs section thus organized all the development docs . Please find the changes here
Improved the README.md and CONTRIBUTING.md so that they serve as an entry point for newcomers and existing contributors.
Reference to the correct files wherever required.

vercel · 2020-10-26T17:45:42Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/kantord/libre-lingo/b2c159sat
✅ Preview: https://libre-lingo-git-fixing-doc.kantord.vercel.app

yash2189 · 2020-10-26T17:48:24Z

@kantord Can you please review the changes ?

yash2189 · 2020-10-26T17:56:42Z

@kantord there are some failing checks , can you please guide me?

yash2189 · 2020-10-27T07:01:51Z

@kantord Any updates please tell me.
Thanks

kantord · 2020-10-27T07:42:17Z

Hi @yash2189, sorry for the slow response, I was with work and other stuff. Reviewing it now

kantord · 2020-10-27T07:44:22Z

the pipeline is failing because a couple of docs files are being referenced in the frontend code. This is because those are also exposed in the web app.

You can look at the failures here: https://kantord.semaphoreci.com/jobs/6b06233d-5d3c-4056a845-75fed2e73e7c

You simply have to make sure that the frontend loads the correct files. If you moved those markdown files, you simply have to update the import in each file that fails

kantord · 2020-10-27T07:46:12Z

https://kantord.semaphoreci.com/jobs/d3ae816e-fde7-4284-a595-45793cddbaa8
the same goes for docs/image_attributions.csv

if you move it around, you'll have to update the path in the import/open usages. For this one file I recommend that if it can be avoided, don't move it around, because it's also used in some scripts

kantord · 2020-10-27T07:53:26Z

docs/contribution_details/CODE_OF_CONDUCT.md

I would actually keep this file where it is, because it's it's standard place on GitHub projects. You can perhaps still link it from the main documentation

kantord · 2020-10-27T07:47:08Z

README.md

@@ -77,20 +77,12 @@ Here's a rough sketch of how  I imagine the milestones of this project:

 ## Become a contributor

-### Contribute to course material
-If you are interested in contributing to course development, please fill the following form: https://danielkantor196881.typeform.com/to/V00Paz. The project is in a very early stage right now, so you might not be able to contribute right away. Your work will be released in this GitHub repository and you will show up as a contributor here.
+We welcome contributions for course material as well development contributions.In order to know more regarding your contributions to our project please checkout the [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/contribution_details/CONTRIBUTING_GUIDE.md)


We welcome contributions for course material as well as development contributions

ns.In

Missing space here

I recommend running this through some spell checker that makes spotting these mistakes easy. Grammarly is one option that runs in the browser. There might be some plugin for your code editor

https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/contribution_details/CONTRIBUTING_GUIDE.md ◀️ that link doesn't seem right! It's linking to your fork. Perhaps the best would be to use a relative link?

(Which makes me realize, that I also did the mistake of specifically linking my fork instead of using relative links)

https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/contribution_details/CONTRIBUTING_GUIDE.md ◀️ that link doesn't seem right! It's linking to your fork. Perhaps the best would be to use a relative link?

Can you please tell me about this @kantord.I'm unable to link this file. As CONTRIBUTING_GUIDE.md is a file that is created under my branch(fixing-doc) how is it possible to give a relative link?

To learn more about relative links, consult the documentation I linked

Or is it wrong/confusing for some reason?

@kantord when I tried doing the same it showed 404 error

hmm, what is the link that you tried that gave 404?

Hello @kantord I have successfully provided the relative link you can check my changes in PR , all checks are passing now

README.md

kantord · 2020-10-27T07:54:39Z

docs/contribution_details/CONTRIBUTING_GUIDE.md

@@ -0,0 +1,28 @@
+# Contributing to LibreLingo


I think this file could just be docs/CONTRIBUTING_GUIDE.md, no need to put it in a folder

kantord · 2020-10-27T07:56:28Z

docs/contribution_details/CONTRIBUTING_GUIDE.md

+
+### Development and other forms of contribution
+
+Check the latest **Development documentation** on [Read the Docs](https://librelingo.readthedocs.io/en/latest/)


This line should not be necessary here, because the person will already be on that page almost certainly

This line should not be necessary here, because the person will already be on that page almost certainly

I was thinking if a person could find the link for the development docs in the same file it might be easier for him to read the other contents inside the same file. Like over here if the person is under CONTRIBUTING GUIDE he can find all the necessary material under one file. Thoughts on this @kantord ?

I think you should just be able to link to that markdown file. mkdocs should take care of the rest.

mkdocs converts these .md files into a static webpage. that webpage is hosted at https://librelingo.readthedocs.io/en/latest, but since the person reading it is already on that page, we don't need to tell them.

kantord · 2020-10-27T07:57:18Z

docs/contribution_details/LICENSE.md

don't move this file, it should be in the root folder

kantord · 2020-10-27T07:58:52Z

docs/development_docs/attributions/attributions.md

no need to nest this into so many folders IMO. I'd just call it docs/attributions.md

kantord · 2020-10-27T08:04:31Z

I would get rid of the docs/development_docs/ folder altogether. Everything under docs/ is already development docs

kantord

Please address my comments

yash2189 · 2020-10-27T08:37:57Z

@kantord Sure I'll work on the changes , apologies for the late response

yash2189 · 2020-10-27T22:28:24Z

@kantord I have removed the unnecessary directories that I had created , still the build is failing,Please tell me about the same.

kantord · 2020-10-28T05:12:08Z

The build is failing, because the incorrect file is being imported on line 60 of this file: /src/routes/license.svelte

yash2189 · 2020-10-28T14:31:09Z

@kantord Can you please check my comments on the above replies that you have made on changes?

yash2189 · 2020-10-28T14:51:13Z

@kantord all checks have passed please review whether I have done everything correctly
Thanks.

yash2189 · 2020-10-28T14:53:01Z

Also please tell me about relative link I'm not aware as how to provide the same

yash2189 · 2020-10-28T20:00:01Z

thanks @kantord I will work on this tomorrow and update you.

sonarcloud · 2020-10-30T06:14:00Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities (and 0 Security Hotspots to review)
0 Code Smells

No Coverage information
No Duplication information

yash2189 · 2020-10-30T21:11:31Z

@kantord can you please review the changes?

kantord · 2020-10-31T06:16:57Z

docs/CONTRIBUTING.md

-* Course editor, implemented using Django
-
-The site is statically built and hosted on GitHub pages, therefore there's no real "backend" or API.
+We welcome all contributions right from development to the course material.


Suggested change

We welcome all contributions right from development to the course material.

We welcome contributions to our codebase as well as the course material.

kantord · 2020-10-31T06:17:29Z

docs/CONTRIBUTING.md

-
-The site is statically built and hosted on GitHub pages, therefore there's no real "backend" or API.
+We welcome all contributions right from development to the course material.
+In order to contribute to LibreLingo you can check our detailed [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/CONTRIBUTING_GUIDE.md)


Suggested change

In order to contribute to LibreLingo you can check our detailed [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/CONTRIBUTING_GUIDE.md)

Check out our detailed [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/CONTRIBUTING_GUIDE.md)

kantord · 2020-10-31T06:18:23Z

docs/CONTRIBUTING.md


 ## Getting started

 Please check out our development documentation for instructions on
 [setting up the development environment.](https://librelingo.readthedocs.io/en/latest/#setting-up-the-development-environment)

-### Pick an issue


Please link the Pick an issue section from the development docs

kantord · 2020-10-31T06:19:50Z

docs/CONTRIBUTING_GUIDE.md

+
+Check the latest **Development documentation** on [Read the Docs](https://librelingo.readthedocs.io/en/latest/)
+
+This project has 2 main components


this is rather out of place here now, this is technical documentation

I didn't understand this @kantord can you please elaborate? Do you want me to create a separate technical contribution file or something else?

kantord · 2020-10-31T06:24:09Z

README.md


-### Development and other forms of contribution
+We follow certain guidelines in order to maintain this repository. Before you start contributing we highly urge you to read our guidelines [here](https://librelingo.readthedocs.io/en/latest/CODE_OF_CONDUCT/)


that link will (I hope) be broken, because CODE_OF_CONDUCT should be in the repo root, and hence will not be part of the dev docs. That's ok, becuase it's its standard place.

Also, this extra text adds little value I think. I would simply link Code of Conduct, but I'd rather link it from CONTRIBUTING.md, what do you think? If you really want to put some text around it, I think it's enough to say "Please read our Code of Conduct"

Yes @kantord I will link the code of conduct from CONTRIBUTING.md doc. Where should I place the code of conduct.md file?

vercel bot had a problem deploying to Preview October 26, 2020 17:45 Failure

yash2189 mentioned this pull request Oct 26, 2020

Clean up documentation #789

Closed

vercel bot had a problem deploying to Preview October 26, 2020 17:52 Failure

vercel bot had a problem deploying to Preview October 26, 2020 18:00 Failure

vercel bot had a problem deploying to Preview October 26, 2020 18:02 Failure

vercel bot had a problem deploying to Preview October 26, 2020 18:07 Failure

vercel bot had a problem deploying to Preview October 26, 2020 18:08 Failure

vercel bot had a problem deploying to Preview October 26, 2020 18:49 Failure

docs: Cleaned up the documentation

8cca49a

vercel bot had a problem deploying to Preview October 26, 2020 18:50 Failure

kantord reviewed Oct 27, 2020

View reviewed changes

kantord requested changes Oct 27, 2020

View reviewed changes

docs: Cleaned up documentation

6d5976d

vercel bot had a problem deploying to Preview October 27, 2020 20:13 Failure

Update CONTRIBUTING.md

2044855

vercel bot had a problem deploying to Preview October 27, 2020 20:16 Failure

Update README.md

0128dc2

vercel bot had a problem deploying to Preview October 27, 2020 20:19 Failure

Update tos.svelte

a61448f

vercel bot had a problem deploying to Preview October 27, 2020 20:28 Failure

docs: Cleaned up documentation

18c490b

vercel bot had a problem deploying to Preview October 27, 2020 20:52 Failure

docs: Cleaned up documentation

9d39ca5

vercel bot had a problem deploying to Preview October 27, 2020 20:58 Failure

docs: Cleaned up documentation

fdaf333

vercel bot deployed to Preview October 28, 2020 14:38 View deployment

docs: Cleaned up the documentation

869242d

vercel bot deployed to Preview October 30, 2020 06:12 View deployment

yash2189 requested a review from kantord October 30, 2020 21:11

kantord reviewed Oct 31, 2020

View reviewed changes

kantord closed this Feb 17, 2021


		### Development and other forms of contribution

		Check the latest Development documentation on [Read the Docs](https://librelingo.readthedocs.io/en/latest/)

	We welcome all contributions right from development to the course material.
	We welcome contributions to our codebase as well as the course material.

	In order to contribute to LibreLingo you can check our detailed [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/CONTRIBUTING_GUIDE.md)
	Check out our detailed [contributing guide](https://github.com/yash2189/LibreLingo/blob/fixing-doc/docs/CONTRIBUTING_GUIDE.md)


		Check the latest Development documentation on [Read the Docs](https://librelingo.readthedocs.io/en/latest/)

		This project has 2 main components


		### Development and other forms of contribution
		We follow certain guidelines in order to maintain this repository. Before you start contributing we highly urge you to read our guidelines [here](https://librelingo.readthedocs.io/en/latest/CODE_OF_CONDUCT/)

docs : Cleaned up documentation #861

docs : Cleaned up documentation #861

Conversation

yash2189 commented Oct 26, 2020 • edited

Description:

What has been added ?

vercel bot commented Oct 26, 2020 • edited

yash2189 commented Oct 26, 2020

yash2189 commented Oct 26, 2020

yash2189 commented Oct 27, 2020

kantord commented Oct 27, 2020

kantord commented Oct 27, 2020

kantord commented Oct 27, 2020 • edited

kantord commented Oct 27, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yash2189 Oct 27, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yash2189 Oct 30, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kantord commented Oct 27, 2020

kantord commented Oct 27, 2020

kantord commented Oct 27, 2020

kantord left a comment

Choose a reason for hiding this comment

yash2189 commented Oct 27, 2020 • edited

yash2189 commented Oct 27, 2020

kantord commented Oct 28, 2020

yash2189 commented Oct 28, 2020 • edited

yash2189 commented Oct 28, 2020

yash2189 commented Oct 28, 2020

yash2189 commented Oct 28, 2020

sonarcloud bot commented Oct 30, 2020

yash2189 commented Oct 30, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yash2189 Oct 31, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yash2189 commented Oct 26, 2020 •

edited

vercel bot commented Oct 26, 2020 •

edited

kantord commented Oct 27, 2020 •

edited

yash2189 Oct 27, 2020 •

edited

yash2189 Oct 30, 2020 •

edited

yash2189 commented Oct 27, 2020 •

edited

yash2189 commented Oct 28, 2020 •

edited

yash2189 Oct 31, 2020 •

edited