search

brahmlower / cssef

Cyber Security Scoring Engine Framework
7 stars 3 forks source link

Create proper documentation #31

Open brahmlower opened 8 years ago

brahmlower commented 8 years ago

I've decided that documentation will be done through Read The Docs. I still need to do some testing with it, but documentation should be clearly divided between user and developer documentation. Along with this, I should consolidate existing documentation. This includes cleaning up documentation scattered through the refactor branch, as well as deleting the crappy wiki I started for the project back when everything was in the Master Branch

brahmlower commented 8 years ago

Inline docstrings should be modeled after the Google's python docstrings, which will feed into sphinx documentation generation using Napoleon. See google example docstrings here and more information about Napoleon here.

brahmlower commented 8 years ago

I've set up sphinx documentation and got it hooked up with read the docs. The docstring documentation that's automatically pulled from the sourcefiles isn't working yet because of issues while importing the packages. Finishing this issue will require that I fix the issues with the packages first.

brahmlower commented 8 years ago

I'm also missing a few processes that have yet to be documented. I'm adding them to the todo list in the initial description

brahmlower commented 8 years ago

Change up the installation documentation to install using the vcs feature in git. Client:

pip install -e 'git+https://github.com/bplower/cssef.git#egg=CssefClient&subdirectory=CssefClient'

Server:

pip install -e 'git+https://github.com/bplower/cssef.git#egg=CssefServer&subdirectory=CssefServer'
brahmlower commented 7 years ago

I got read the docs working with autodoc a week ago, so documentation is generated based on docstrings now. I'm marking off WebAPI here, since I've completely removed it from the codebase.

brahmlower commented 7 years ago

With the structure of the development documentation in place, I'm going to finish migrating the old documentation in the repo. References to end user and developer sections of documentation should be included in each readme.

Old readme content is located at the following locations. Each of these should be changed to rst files, to maintain a consistent method of documentation throughout the repo.