codethesaurus / docs Goto Github PK

The name field within a concept is pulled from the meta language files now and is not used in thesaurus language files anymore. This can be removed from the documentation.

Also the comment field has been added to allow for someone to describe parts of the code and explain what the different variable names or keywords refer to in the code.

Both of these should be edited in the Thesaurus Files page but anywhere else there might reference to them.

There is a lot of detail in responses to Issues and comments in PRs. These could be used to fill in the empty FAQ.

Can I be assigned this task to get it started?

For example, from issue #225

What does "Not implemented in this language" mean exactly?
This means that this feature is a thing you can look up on Code Thesaurus, but doesn't necessarily mean the language can do it. So not all languages can do all things other languages can, so this is a way of marking in the file "we're looked at this in the file, and this language can't do it."

settings.py has these two lines which try to reach the database specified in DATABASE_URL environment variable - which is not supposed to work for anybody doing local setup.
I was able to get it running because I recognised the URL being picked up as one of mine and found the corresponding lines to comment:

# db_from_env = dj_database_url.config(conn_max_age=500)
# DATABASES['default'].update(db_from_env)

It might not be immediately apparent, especially to thesaurus only contributors -- can we add this piece of instruction in the local setup docs? Happy to open the PR myself, if this seems like something that can be done.

There needs to be a page that shows how to run the MkDocs generator to locally run the documentation site for testing and editing.

When someone adds a new language, they also need to add a folder for the version. And, if they are adding files for structures, they will not be able to get the templates from the URL as given because the language will not exist in the live site - so they need to use their local version.

Fix should be simple. Something like:

In Add on a New Language after " From there, assign it to a directory name in the JSON structure." Add the directory and a subdirectory for the latest version (or the version you are providing)

In Add an Existing Structure Set to a Language Say, if you are adding a new language, get the structure templates from: "localhost:8000/reference/?concept=<your_concept>&lang=%3B<language_major_version>" or something like that.

Noticed a broken link for the README in step 4 on the /contributing page.

Make sure you test the changes. Check out how to run the project on the README.md page.

Links to https://docs.codethesaur.us/contributing/README.md which 404's.

I think this really should point to the Installation page in the docs since that's where the README redirects folks to.

The path to quick start has the .md attached, so it doesn't show up even though there is data.

Looks like https://docs.codethesaur.us/quick_start.md and pretty sure it should look like https://docs.codethesaur.us/quick_start/

But also, that change alone does not fix the problem - perhaps the updated file was merged in as markdown but the website was not compiled afterwards?

There are two new commands you can run in Django:

• python manage.py validatemetainfofile
• python manage.py validatelanginfofiles

The former ensures meta_info.json is filled out right and the directory structure matches what the file expects.

The latter ensure all language data files pass a variety of warning and error checks to prevent either the site breaking or just confusing results that aren't what's expected.

Both run on every PR now, but also they can be ran from the command line to check the files yourself.

Add this information in an appropriate place in the docs!

Build a Docker image so one doesn't need to install Python or mkdocs on this site.

(It should be similar to https://github.com/codethesaurus/codethesaur.us/blob/main/Dockerfile except instead of running the Django site, it'll run the MkDocs server instead.

See https://www.mkdocs.org/#installation for more on the MkDocs executable.

I moved many of the .md files over to this docs repo for docs.codethesaur.us. Some of the formatting didn't transfer over right.

Go through each of the .md files in this repo and just make sure the expected formatting actually turns out right on the actual site.

There are cases where I see multiple people tackling adding in a language's concepts, but they do it in vastly different ways. There needs to be a page that can be shown to people to sort of be the "truth" to how to do things.

Things to include (but not limited to):

• Code blocks must technically compile
• Try to leave comments out of code blocks and put in comment blocks instead
• Try to have code blocks match other code blocks as much as possible
• If there's more than one way to do things, you can write both in a code block, but differentiate them with a comment
• Anything that's not intuitive to a beginner needs a comment
• Operators need to show order (prefix, postfix, infix)
• You should have code, or code + comment, or not-implemented, or not-implemented + comment
• ...

The install directions for Code Thesaurus still show how to spin up the Docker container manually. A Docker Compose file was added to make this a lot easier, but the instructions weren't ever updated to reflect this.

1. In the install directions, add a section above the other two (Docker Container and Manual Install) for Docker Compose
2. Add instructions on how to run it. (It should be, I believe, just docker-compose up)
3. Verify and test the instructions work for you

If you can test it in one operating system, it should work for the others. (i.e. if you test in Windows, it should work the same in Mac.)

What I propose

For each structure there should be a documentation page that explains every category in more detail.

Why this is a good idea

It can be hard to correctly implement a structure file cause it is not always clear what a category is about just from the short category header alone.
This would make it easier to find it out and thus it would help to keep implementations across languages more consistent

Possible implementation

# Lists, Arrays, and Hashed Lists
Data structures that keep multiple objects together.
<dl>
  <dt>List</dt>
  <dd>A data structure that keeps multiple elements often of the same type</dd>
  ...
<dl>

## Ordered Mutable Lists
Concepts for a mutable list that keeps the elements put into it in the same order.
i.e `print OrderedList(5, 6, 3, 4) => "[5, 6, 3, 4]"`
### Examples
- Python: `list`
- Haskell: `List`

## Sorted Mutable Lists
Concepts for a mutable list that keeps the elements put into it sorted (by value or something similar).
i.e. `print SortedList(5, 6, 3, 4) => "[3, 4, 5, 6]"`
### Examples
- C#: `SortedList`

## More Categories ...

There's lots of info on getting started but not much on testing. Perhaps it needs its own page. It can also include directions on how to test locally (via Python) and in Docker (via docker run or docker compose run).

Specifically, I could see it describing how to test:

• new code written (running unit tests)
• adding/modifying new language files (via the validatelanginfofiles command and also going into a browser and looking at it)
• adding new languages or structures (via validatemetainfofile command, adding one sample language file, then checking the reference page to make sure the concept seems to be loading and appearing correctly)

Not many people seem to test things locally and this could help people understand how to do it.

There's a lot of deep-dive pages, but so few people read those. The project also tends to attract some newer to development people (which I love!) but it means they need a bit more hand-holding than I have the capability to give.

I'm wondering if we need a page that's a super quick "how to get started" kidn of page that, if someone doesn't want to read all the pages related to what they're doing, can at least follow the like 8 steps to get going on this page. This could replace the steps I keep putting in CT's issues with several steps in it.

I don't want this to replace other pages, more like supplement them. Like when you buy a new device/appliance and it comes with the 40 page manual but also a quick one page sheet to get you going faster. That, but for Code Thesaurus.

The manual instructions at https://docs.codethesaur.us/install/ might need to mention that a first time install requires a database migration step.

Based on discussion with @geekygirlsarah, the command needed before the runserver step is...
python manage.py migrate

Propose adding a step to the manual install instructions as...
(first time use on new installs) Run python manage.py migrate to upgrade the database

For whatever reason, M1 is a vastly different system and the regular instructions for Mac don't work for installing CT. @Layla-P and I figured this out while working on it. Notably:

• Docker is completely incompatible with M1 processor
• brew installs packages to different locations compared to Intel Mac
• Need to work around Mac's built-in Python vs needing Python 3 for CT

If someone wants to research this, it'd be appreciated. If not, I have the video of when @Layla-P and I did this on stream and can watch it over to recreate the directions.

Similar to Code Thesaurus's README page, make this have some helpful info on how to contribute, how to install, and Code of Conduct. It can just be similar to the CT's website README only modified to work here. Links should point to docs.codethesaur.us wherever possible.