Documentation generation

[etpeterson]

Feature description

There's currently no documentation being generated. It would be nice to have some basics at least.

Describe the solution

This would involve using pydoc or sphinx to build documentation. It might be tricky because the original source may have no documentation, or documentation of differing types. This might need to be ignored. The wrapper code might have some useful documentation, but may also need expanding before it is truly very useful.

Describe alternatives

No response

Additional context

This may be more difficult than expected because of the varieties in coding styles and the wrapping. It might also require more baseline documentation to be written before it is useful.

Are you working on this?

None

[AhmedBasem20]

Hey @etpeterson I would love to give this a try, I used sphinx before so I may try it. We need to build the content of the /doc folder and generate api documentation as well, right? I think we might also need to add pre-commit hooks to ensure that the code is well-styled and documented, which will subsequently impact the API documentation. Let me know what you think about this.

[etpeterson]

Yes, it could be a big job. It's important to go light on this because the outside algorithms won't follow any guidelines we set, so that could be ignored or parsed optionally. That's the src/original folder. I wouldn't necessarily block merges on documentation at this point, but it would be nice to warn. Also, just being able to build docs might be the first step, with the followup to be build and check automatically.

[Aditish51]

Hello, @etpeterson This is Aditi. I have some experience in building docs with sphinx. So Can I just start trying to work on it? # think I need to work on the src/original. Please correct me if I am wrong. Can you assign this to me?

[etpeterson]

Hi @Aditish51, glad that you also want to work on it with @AhmedBasem20. It sounds like you both might know more about Sphinx than me. Is there a way to easily split this project into 2 parts?

My thoughts are to split it into documentation generation and documentation automation, but I'm open to suggestions.

Also, can you assign this to yourselves or is that something I need to do?

[AhmedBasem20]

My thoughts are to split it into documentation generation and documentation automation

I agree, I think we need to publish it somewhere after generating it, I see this: https://readthedocs.com/ is commonly used to deploy sphinx documentation.

I tried generating API docs from src/original but this is still in progress, I think we need to add the documents in /doc folder as well, and we should navigate for what we want from the root page. This way, we can just write future document files manually and it will be deployed automatically.

[Aditish51]

@etpeterson I am ready to work on the documentation generation part. You can assign this to me. Here is what I tried to generate the index page for the src/ directory.This is just a basic sample. I will make it correct.

Please check this. I can change the design if you want. Can I send a PR for this?

[etpeterson]

The src/original is the original code and may not be standard in any way. It could yield something but better would be the wrapper code. Nothing has much documentation though.

[Aditish51]

@etpeterson Can you please explain me more on which directory I need to work upon i.e. whether I need to work on src/original or the standard wrappers inside it .I think there are three sub directories inside the src/original which contains wrappers. please correct me if I am wrong and guide me a bit more.

[etpeterson]

I think the key is flexibility for this. Ideally it would "work" on any folder, but the src/original is submitted to us and we don't have much control over what is in there. If they're thorough then it would have documentation, but most likely not. The sub directories are individual algorithms which are submitted to us which we then wrap to allow consistent use and testing.

Then there's the src/standardized which is the wrapping of the original into our structure. This we can standardize and make consistent with our structure. It might not contain much now, but we could make this something that generates good documentation.

Starting with what's in src/standardized would be good, but also using what is in src/original, if anything. Perhaps they could be linked in some way to prevent duplication?

[Aditish51]

@etpeterson I think for now I can work upon just src/standardized instead of whole src / directory this would probably not duplicate things with src/original