-
Notifications
You must be signed in to change notification settings - Fork 2
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
Support for several source dirs #19
Comments
This seems to be two issues, not one.
There may be problems though not in Pod::To::Cached. I think when I was developing Pod::To::Cached I included p6 and pm, but ran into problems elsewhere. Or perhaps, I was focussing on the documentation suite, which does not contain p6 or pm files. |
Ok, I just included p6 and pm as possible extensions. The tests all passed. However, my test suite does not contain p6 or pm files. It would be useful to add tests that include p6 and pm files. So part 2 of this issue seems to be easily resolved, but I anticipate problems somewhere done the line. Updating Pod::To::Cached |
Regarding multiple sources.
I am reviewing the code to see how to change it, but I would appreciate some help on the test suite. |
Mmm, you're right, this feature would introduce a lot of weird cases that, probably, we cannot cover. Maybe we should simplify this and only let the use of a "docs" folder and "lib". Or maybe only the "docs" directory. I do not understand the last point you have made, can you clarify, please? Of course, I will help with the test suite. |
I've been looking at the code, and the change to multiple sources has numerous problems. It may even require a change in design. Source is not just a directory, it specifies a directory tree, under which documentation is contained. This assumption is used in the naming convention for the cache, in that the full path to each document is truncated using the length of the path for the source. The aim of this naming sequence is to make it easier to freeze the cache by making the names relative to the cache, not to the full path. Changing from one source tree to many source trees means that every document will need to be named with the full file path of the document.
|
|
|
@antoniogamiz Note that I said 'language' not 'languages'! I meant documentation for modules as opposed to documentation of the perl6 language itself. So when you refer to documentation of Perl6::Documentable, this is a module but not a part of the Perl 6 language. In principle, your extension idea is important. In the future, it will be important for a developer to know about functions that are supplied by all the modules installed on a system, not just the functions that are available from the Perl 6 language. We are focussing on the Perl 6 language documentation at the present, but we should keep in mind that extensions will be needed for all modules, and perhaps on line, for all modules in the ecosystem (???) |
Ah I see. You're right, @JJ wants that Nonetheless, I think that support to all modules installed in a system is a bit out of the scope of Perl6::Documentable. In my opinion, that feature fits with 'p6doc'. |
Could this be fixed with several copies of Pod::To::Cached? Or of Perl6::Documentable? |
@antoniogamiz Perl6::Documentable is a high-level API for all kind of documentation. You might have different instances for different root dirs or the same instance, it's not really a big difference. p6doc should always rely on Perl6::Documentable, not go directly to the cache. |
Ah, that's a good idea. I will do it, thanks for the point. |
we are agreed, I think. This suggestion has a better work around. But testing required for multiple instances. |
Problem
At this moment, we can only specify a single source directory with
:source
. My idea convert:source
to an array.Why do I want this?
Perl6::Documentable
supports pods inside files containing code (.p6
,.pm6
, etc), so in order to use them, we would need to specify `:source("lib"), to gather all documentation in our module.In that case we face two problems:
Pod::To::Cached
does not support those extensions (I suppose that's easy to fix):source
. What if we want to create an additional directory containing tutorials in pod6? We would need to use:source("<module-root-directory>")
.The last fix is a hack I don't like because you can have pods in your module root directory, which you do not want to be used by
Perl6::Documentable
.Suggestion
.p6
and.pm6
files.:@source
.This is only my idea, please let me know your opinion.
The text was updated successfully, but these errors were encountered: