search

GrammaTech / ddisasm

A fast and accurate disassembler
https://grammatech.github.io/ddisasm/
GNU Affero General Public License v3.0
645 stars 60 forks source link

Refactor documentation. #63

Closed gogo2464 closed 1 year ago

gogo2464 commented 1 year ago

Hello,

I reorganized the documentation with the template from https://documentation.divio.com/ !

Now we just have to do make html in order to build html documentation. make pdf for pdf documentation and so on.

I found it so much easier than the pandoc complicated way. I kept pandoc code in case there were a logic behind.

The api ref was well documented. I kept it.

Best regards.

gogo2464 commented 1 year ago

I had accidentally included .html and .doctree files. I must remove these.

gogo2464 commented 1 year ago

I removed these. Should I also add a .gitignore to src/datalog? I ignore if it has been autogenerated.

gogo2464 commented 1 year ago

@aeflores should I remove the doc/source/3-REFERENCES/src_docs/* binaries please? Could you do a review after?

aeflores commented 1 year ago

Yes please, remove the src_docs/* files, those should be autogenerated.

gogo2464 commented 1 year ago

Could I remove everything under https://github.com/GrammaTech/ddisasm/pull/63/files#diff-f48ddfd1eec38c4d39f84e195259371f8397cd30146f46b113bdcb4590ed262cR16 please? My way seems more flexible with more format and is easier to understand.

Everything else is ready to merge.

gogo2464 commented 1 year ago

I have an issue with linking the manual. I have output to .rst instead of .html. everything else should be fine!

gogo2464 commented 1 year ago

@aeflores ready for a new review. Sorry for the mistakes. I probably need to be more incremental.

gogo2464 commented 1 year ago

Hello. Sorry I am very very late! I think there are a lot of good improvment in my PR.

I am very busy these time with work.

Can I finish this PR this month?

aeflores commented 1 year ago

Hi @gogo2464, this is on me, I have it on my list to do a last pass and merge it, but I haven't had the time.

In the meantime, I enabled web deployment https://grammatech.github.io/ddisasm/, so I want to make sure the new documentation will get correctly deployed once it is merged. I will take care of it next week.

aeflores commented 1 year ago

Hi @gogo2464 we finally merged some of these changes here https://github.com/GrammaTech/ddisasm/commit/b92b5462006695e7f7faf996d925df7120533686

you can take a look at the refactored documentation https://grammatech.github.io/ddisasm/

In the end, I removed some of the categories where we did not have any content or the content was incomplete (some of the tutorials). I also did not include some of the pages that you created like the discussions on reverse engineering. These are pretty general and would make more sense as a separate blog post than as the official ddisasm documentation.

All in all, we kept the idea of having a main landing page with a few categories rather than just the Datalog API. Thanks for your contribution!

gogo2464 commented 1 year ago

It sounds good for me. I saw you removed the 4 th chapter. You probably found it useless. I used this template to make the doc more understandable https://documentation.divio.com/ . If you found it useless, there is no issue. I want to help you. I do not want to make ddisasm dev slower.

Sorry for the time that I spent.