Needs Project Documentation

Chris-Johnston / Easier68k

Work In Progress - A Python M68k assembler and simulator.

https://chris-johnston.me/Easier68k/

MIT License

15 stars 6 forks source link

Needs Project Documentation #96

Closed Chris-Johnston closed 5 years ago

Chris-Johnston commented 6 years ago

This project as a whole could use more documentation in the form of a website. Stuff that needs to be documented includes:

FAQ
Guides on how to use the software (and how to contribute to the software, including testing)
Documentation on what the opcodes do, including CCR
- TRAP codes as well
Interfaces & API definitions (properties and methods for each of the object types)
Probably others that I'm forgetting.

There are a few options that I'm considering for this:

GitHub pages / GitHub wiki
Whatever docs https://docs.python.org/3/ uses
http://www.sphinx-doc.org/en/master/
Others?

adityac8 commented 6 years ago

I suppose we can have a look at OpenWISP and generate a simple site using sphinx. What do you think @Chris-Johnston ?

Chris-Johnston commented 6 years ago

I've seen that Sphinx and Read the Docs are pretty common with stuff like this, and I actually had started setting it up in #103 , but never got around to getting anything implemented yet. Might be something that I come back to in a few days.

adityac8 commented 6 years ago

Great @Chris-Johnston I suppose having a separate repo for docs would be easier to maintain.

Chris-Johnston commented 6 years ago

It's not actually going to be in a separate repo, like the openwisp2-docs. The docs will be under a docs directory, similar to how tweepy does it.

Thanks for the suggestion for using sphinx though, I think that may be the way to go.

adityac8 commented 6 years ago

I had a look at tweepy. That is also a good idea. We can look at openwisp2-docs README and add a similar one to the docs folder for giving the users an understanding of making contributions and an intro to sphinx.

Chris-Johnston commented 6 years ago

Definitely, contribution and getting started guides are both important to have, but haven't been a focus of development yet. I want to focus on cleaning up the code base a bit before focusing on other contributions.

adityac8 commented 6 years ago

Sure! I am happy to help with the docs once you are done

cleaning up the code base

Chris-Johnston commented 5 years ago

Fixed as of #103 . Now using Travis CI to build Sphinx docs, which are deployed to GH pages.