[Suggestion] - Mkdocs Material as the base for documentation

[tarsil]

Thank you everyone for the great project. Apologies if this PR looks big but in fact is just the initial setup. Let me explain what is this and how it does work.

I'm an opensource contributor and the creator of Esmerald framework. I absolutely love your project and I thought I could help you with some PR and contribute to the growth and health of the codebase (if allowed, of course).

n the last few years, Mkdocs Material became almost a must have for documentation of these type of projects. I know a lot of people also prefer sphinx which is very mature and amazing as well, I just find mkdocs-material easier to setup.

Besides Esmerald and some other opensource projects I have built, there are a lot of known projects also using this package for their documentation, for instance, Pydantic, FastAPI, Mkdocstrings and list goes on and on.

I though I could initially suggest for this PR a move to this tool and from there it would be a lot easier to grow and maintain the documentation.

I had the pleasure of talking with one of your team members about this and I thought it would be nice to suggest and see how it goes. Mkdocs Material.

Deploying it it is extremely easy and even maintaining a consistent API Documentation won't be so hard since Python has some defaults that can help you with that to automatically generate those for you. Example of an automatic generated API Documentation would be like this one.

How to test this

I added some extra make commands to make it easier for everyone who wants to contribute, to be able to do it easily like running documentation locally, installing requirements without headaches...

make requirements-local

or

scripts/install

Will make sure it will install all the requirements in your local machine (including for docs).

scripts/docs

Will start the documentation locally and by default serving on https://localhost:8000.

How to add documentation with mkdocs-material

Well, as you can see from the PR, if you want to add a new file, for example a page called filters, you only need to do this:

1. Inside the docs/ create a file called filters.md.
2. Add the filters.md to mkdocs.yml under the nav: section and that's it!

Of course if you want to create documentation sections, the docs of mkdocs explain well but it would be like (inside mkdocs.yml):

...
nav:
   - New Section Name:
      - "filters.md" 

What is this scripts folder

As per README, it follows a practice "Scripts to Rule Them All".

How to deploy

I could see your docs are published using github actions, so it is already 99% done and mkdocs material actually gives you a clear example how to do it quicky.

Something around this line - run: mkdocs gh-deploy --force.

[jmcorreia]

Hi @tarsil :).
First of all, thanks a lot for your contribution into the project! 🚀 We will give it our best attention.
For now, our documentation is being done automatically with pdoc. This is the documentation we are serving, in addition to a bit of customisations to have search bars and examples attached in the code.
Based on this, recently, we started an effort to check how we could add custom markdown files into the documentation, so that we could make it a lot more custom. We actually already have a working POC (with considerably less changes), but could not find the time to bring it yet. We can share more details if you would like.
My other comment would be, would your contribution play well in conjunction with our current setup with pdoc and customisations I mentioned?

[tarsil]

@jmcorreia im not 100% familiar with PDoc as it not too much used (at least for my knowledge) by the community, of at least I haven't seen so much but nothing like having a look. What I do know is that mkdocs-material integrates extremely well with exactly you have described that you'll eventually need 🙂 but it's of course all up to you and your team. This was just a working suggestion that could facilitate your documentation in the future. As per automatic API documentation, there are native ways of making this work as mentioned by the PR 🙂

[jmcorreia]

@tarsil , just to give you some more feedback after some time. We have taken a decision, internally, to prioritise the offering of more documentation using the current library (pdoc) to speed up easy adoption of the framework, which is currently lacking examples for a few algorithms and usages.
The plan is that we do it in a way that all the delivered documentation will be easily re-used in a later migration to mkdocs as you have proposed.
This means the migration to mkdocs is planned, but will happen at a later stage.
With that said, I thank you again for your amazing contribution!

I will leave this PR open until we migrate to mkdocs, so that we can track and even collect more feedback if needed.