IntelOwl
IntelOwl copied to clipboard
intelowlproject
Move from ReadTheDocs to Mkdocs by leveraging Github Pages
Mkdocs reference: https://github.com/mkdocs/mkdocs
We could host the site via Github Pages. See how OpenCTI does it here: https://docs.opencti.io/. They use this style
In this way we would have a centralized place for documentation and we can change it without the need to make a release in the Project itself.
All the documentation regarding the list of plugins name can be kept inside this repo to avoid to have the contributors that create a new analyzer to update 2 repos at once.
This would also solve other problems we have with ReadTheDocs for the GreedyBear project which would need to be included in that new documentation too
It could be helpful to follow this guide.
I would remove completely the ReDoc API documentation and the related code (see add_docs and drf_spectacular) and leverage a new way to document the APIs that is less impactful and more easier supported.
It is also important to add a section dedicated to PyIntelOwl in the new documentation. Move/deprecate what there is about the PyIntelOwl documentation here. Then leverage docstrings or whatever to build the new documentation for the PyIntelOwl library
Hey @mlodic I read the guide you provided. It seems evident that the features of mkdocs can be leveraged by writing code with docstring comments. This in-turn would keep the docs updated and save us extra hassle. I'm curious and please correct me here if I'm wrong; to migrate to mkdocs, wouldn't we have to make sure that our already existing codebase is rewritten well with docstrings??
@mlodic I've experience working with MkDocs and have contributed to projects who have their documentation based on MkDocs.
Hey @mlodic I read the guide you provided. It seems evident that the features of mkdocs can be leveraged by writing code with docstring comments. This in-turn would keep the docs updated and save us extra hassle. I'm curious and please correct me here if I'm wrong; to migrate to mkdocs, wouldn't we have to make sure that our already existing codebase is rewritten well with docstrings??
We may have to modify and add the docstring to the codebase little by little. What do you think @mlodic.
Docusaurus reference link: https://github.com/facebook/docusaurus
@mlodic, can we use Docusaurus by Meta for this documentation ! Seems like a good fit for our docs. Centralized location, easier updates, and less work for contributors. We should discuss integration and maintenance before deciding.
Docusaurus is a cool project but I'd like to understand the advantages that we would have if we compare it with MkDocs. I would like to prioritize something simple and easy to be used. We don't need particular advanced features
@mlodic docsify is also good check once https://docsify.js.org/#/?id=docsify
@mlodic I think Docusaurus is a good fit for this particular use-case. Can you assign it to me so I can start working on it?
@mlodic The MkDocs is a good fit for migrating all existing docs to it. We can easily migrate all docs easily. Let me know what you think.
