Skip to content

Conversation

@sreyassabbani
Copy link
Contributor

@sreyassabbani sreyassabbani commented Jan 16, 2025

(#11) Changes made so far:

  • added a new examples directory currently containing 1 markdown file of mini/starter-examples.
  • updated pyproject.toml to exclude this directory.

Questions:
The style of the examples I'm adding makes it feel more like a tutorial and less like a list of examples, which would be what the name of the directory suggests. I'm looking for feedback as to how these docs should be structured (the overall style, tone, and structure), just in case there are standards/expectations I would need to conform to.

@skysomorphic
Copy link
Member

There is currently no set standard to how the documentation should be written, since most of the existing docs are just autogenerated from docstrings, feel free to go wild lmao (within reason of course).

Are you familiar with the reStructuredText file format? It is more powerful than markdown for use in documentation and is the preferred format of choice for our docs tech stack. This project uses Sphinx and Read the Docs to generate and publish documentation on the web, all the content and code of which is located under the docs/ directory.

RST is fairly simple to learn, and it would be best if new docs is incorporated into the docs published online. Though, it's not a big deal since converting from markdown to RST is not particularly difficult. It can always be done at the end as a final commit, if you don't want to switch while in the middle of writing. Apologies that this wasn't communicated earlier, I'm currently sick with covid lol. Actually, that reminds me to go write a CONTRIBUTING.md.

@skysomorphic skysomorphic added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 17, 2025
@sreyassabbani
Copy link
Contributor Author

I haven't heard of it before, but it seems interesting. I guess I'll switch to RST now instead of waiting later, because it might offer "nice things" that Markdown just doesn't have–so a direct translation wouldn't be able to produce those "nice things".

I apologize I've been disturbing you–Covid is horrible. Hope you get better soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants