Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document effects on code/image #37

Open
snunez1 opened this issue Aug 22, 2023 · 5 comments
Open

Document effects on code/image #37

snunez1 opened this issue Aug 22, 2023 · 5 comments

Comments

@snunez1
Copy link

snunez1 commented Aug 22, 2023

The about this fork section explains the goal of removing heavyweight dependencies, as the doc system becomes incorporated into the production code.

It would be helpful to have a section that explains exactly what effect using the system does have. A list of variables, macros, functions, packages, etc. Basically a comprehensive, but brief, explanation of what happens to a users system if they adopt this documentation package.

@svetlyak40wt
Copy link
Member

Actually, since I wrote this part of the documentation, I've changed my approach and now separate documentation and code ASDF systems just to not add any dependencies need only for docs at all.

I also have a templates for new projects which use this approach: https://github.com/40ants/project-templates

This way text of documentation is still keeped close to the code, but chapters are stored in lisp files in a separate docs directory.

@Symbolics
Copy link

Ah, I see. So now it's only a defsection macro? It might be worth calling out that this is the only change. It's rather non-intrusive to import a single macro. Maybe also provide its definition on the same section.

@svetlyak40wt
Copy link
Member

I'll think about it. If you would like to propose any changes, feel free to create a pull request. Let's make this documentation package great together!

@Symbolics
Copy link

I'd love to work together with someone on a documentation. In fact I've already started on one based on an existing package, declt, just like you did. Perhaps an email discussion on the pros & cons of each is a good next step. I couldn't find your email address anywhere though.

@svetlyak40wt
Copy link
Member

I've created a GitHub organizations for comparison of different documentation builders. It even have you projects for them. Here is declt project. The readme lists my pros and cons https://github.com/cl-doc-systems/declt

We can discuss the in the issues. Or you may write me privately to svetlyak.40wt at gmail.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants