search

melisgl / mgl-pax

Documentation system, browser, generator.
https://melisgl.github.io/mgl-pax-world/
MIT License
75 stars 13 forks source link

Added a separate system mgl-pax-minimal #8

Closed svetlyak40wt closed 3 years ago

svetlyak40wt commented 3 years ago

It has no dependencies and can be used in any library to define documentation sections.

I also added two CI workflows. Both of them are using Github Actions, which I've created for testing CL systems and building docs:

I've created a test pull into my own fork, to demonstrate how do actions work. Here is the resulting documentation:

https://svetlyak40wt.github.io/mgl-pax/

By the way, run-tests action automatically uploads code coverage report to the Coveralls. Here is an example of results:

https://coveralls.io/builds/37324985/source?filename=src%2Fpax.lisp

melisgl commented 3 years ago

Thank you. Regarding WIP, I think the core design problem to be solved is how to deal with client systems depending on pax. In order not be break them, in addition to DEFSECTION, basically everything in pax.lisp needs to be loaded. Factoring out the implementation of documentation generation into its own system may be the way to go.

svetlyak40wt commented 3 years ago

I'm planning to create a parallel pull with rewriting docs to MGL-PAX for https://github.com/40ants/log4cl-extras and will see what will be required to refactor.

svetlyak40wt commented 3 years ago

@melisgl please, review this pull. Seems it works now. I've used this version from my fork to document a few of my systems.

svetlyak40wt commented 3 years ago

@melisgl what do you think about the way how I've separated packages?

svetlyak40wt commented 3 years ago

Gabor excuse me for pinging you again and again, but I'm decided to rely on MGL-PAX as a documentation builder for all of my libraries and without this change, I can't use MGL-PAX because the version which is in the master branch and Quicklisp will add multiple extra dependencies to each library.

melisgl commented 3 years ago

This is what I was mentioning earlier, wouldn't this break if a system uses mgl-pax-minimal and a locative that's defined in pax.lisp such as INCLUDE? I still think that factoring out the documentation generation code only is the way to go. M-. should also keep working even if documentation dependencies are not loaded.

svetlyak40wt commented 3 years ago

Do you mean I have to leave most symbols inside mgl-pax package and make another one like mgl-pax-generator with document function and other facilities dependent on (:3bmd :3bmd-ext-code-blocks :alexandria :babel :cl-fad :colorize :ironclad :named-readtables :swank).

Am I correct?

svetlyak40wt commented 3 years ago

Probably also the Swank integration should be extracted into a separate system, because there can be integrated with other systems like Slynk, Lem, LispWorks.

svetlyak40wt commented 3 years ago

Moreover, I'd like to refactor doc generating code into a CLOS based extensible one. This way everybody will be able to hack the way how HTML is generated and to create custom themes. (But this will be a separate pull-request).

melisgl commented 3 years ago

Yes (to the mgl-pax-generator question). Swank integration: yes, that could also be factored out (maybe to an mgl-pax-interactive system?) HTML generation: Depending on what kind of customization you have in mind, this can easily get very complicated.

svetlyak40wt commented 3 years ago

@melisgl don't you mind if during refactoring I'll convert mgl-pax to ASDF package inferred system and make more files to separate functions and make modules more manageable?

melisgl commented 3 years ago

I am not familiar with inferred systems, but from a quick read of the documentation it seems that there is a one package per file constraint. I'd rather not go there.

svetlyak40wt commented 3 years ago

@melisgl yes, there is a separate package per file. But usually, you can have one package which will be used to gather public API, like:

(defpackage mgl-pax
   (use :cl)
   (nicknames :mgl-pax/core))

Package-inferred ASDF system gives a few profits:

Probably, I should create a fork with a separate name, to not break backward compatibility and to make this big refactoring.

melisgl commented 3 years ago

Based on your summary (thank you!), I'd prefer having explicit package definitions and as few packages as possible. If there is a case to be made for factoring out a system (e.g. emacs?), then that should be carefully considered on its own. As to inferred or not, this implies not inferred.

daewok commented 3 years ago

I would love to have a way of using defsection without also needing to load the documentation generation dependencies. To date, I've been using a brittle and not very extensible hack to accomplish this.

@svetlyak40wt let me know if there's any way I can help make first class support for this a reality.

svetlyak40wt commented 3 years ago

@daewok I've created a fork which is now has incompatible codebase: https://github.com/40ants/doc (https://40ants.com/doc/). Now using it in my libraries.

Here is a request to include it in to the Quicklisp: https://github.com/quicklisp/quicklisp-projects/issues/2030

melisgl commented 3 years ago

I'll rather there were only one version, but I had some reservations about Alexander's choice of implementation (see above). I'll factor out the generation code into a separate system.

mdbergmann commented 3 years ago

I'd also like there is only one library source. Please all figure out a way forward.

svetlyak40wt commented 3 years ago

Please, take a look at TODO section where I've highlighted features I want to see in a documentation builder. I think it will be much easier to implement when a system is implemented in a package inferred way.

mdbergmann commented 3 years ago

I don't say that 'package inferred' is not a good thing. But since the source/package structure here is not complex at all I'm not sure how package inferred system will help to make enhancements much easier. But this is just my opinion. Creating a fork where the original project is still being maintained probably creates confusion for users.

svetlyak40wt commented 3 years ago

But since the source/package structure here is not complex at all I'm not sure how package inferred system.

For me, having many concepts mixed together in two files makes it very hard for anybody except the maintainer to understand the codebase and to introduce improvements :(

Creating a fork where the original project is still being maintained probably creates confusion for users.

Sometimes this is the only option when you want to contribute radical changes. However, if after some period of stabilization @melisgl will think my fork is ok, I would be happy to merge both projects back.

mdbergmann commented 3 years ago

For me, having many concepts mixed together in two files makes it very hard for anybody except the maintainer to understand the codebase and to introduce improvements :(

C'mon. Thousands of Lisp projects were built without 'package inferred' system, for decades. It is completely legitimate and a matter of taste to use one or the other. Your taste is to use 'package inferred'. OK. But the argument is not because it makes thing so much simpler. At least not for this project.

Sometimes this is the only option when you want to contribute radical changes.

For collaboration it is important to make compromises. You can of course do what you want, like make your own fork. But distributing it also (next to MGL-PAX) via quicklisp is a bit contra productive.

svetlyak40wt commented 3 years ago

Thousands of Lisp projects were built without 'package inferred' system, for decades.

It is ok to have a single package but it is not to have all code in a single file with vague dependencies between components. At some point of time, the project needs to be reorganized. Package Inferred system just helped me to divide (and conquer) components and to figure out their dependencies from each other and from external libraries.

But distributing it also (next to MGL-PAX) via quicklisp is a bit contra productive.

Let's talk about productivity when you (as me) will spend a month refactoring the library trying to figure out how each part works. I need this library in a Quicklisp because all other libraries of mine will depend on it.

mdbergmann commented 3 years ago

Modularity is of course good for maintainability. Whether as package inferred system or not. Don't get me wrong. I just would favour that development could be streamlined in one project. I can understand the reservations of the author for 'one-package-per-file'. There are probably other ways to modularize, as the author outlined.

melisgl commented 3 years ago

Pushed e6df2d855834caedeb4f14d617df5a2e140cd8e0 with lazy loading of some dependencies. Feedback is welcome.

svetlyak40wt commented 3 years ago

Oh, excuse me, dude, I've already gone so far in the refactoring of my fork that it is mostly a separate documentation system, based on MGL-PAX's ideas and compatible only on some basic syntax level. It supports custom themes, generates helpful warnings, has built-in search, etc.

I already use this fork for my libraries and has no time or motivation to try improved MGL-PAX. But I hope, now you can borrow some ideas from my https://40ants.com/doc/

mdbergmann commented 3 years ago

Pushed e6df2d8 with lazy loading of some dependencies. Feedback is welcome.

Excellent.

melisgl commented 3 years ago

I already use this fork for my libraries and has no time or motivation to try improved MGL-PAX. But I hope, now you can borrow some ideas from my https://40ants.com/doc/

Thanks, I'll certainly have a look.