General comments

[tbrowder]

Some thoughts I have from initially playing with documentable in a fork of the doc repo:

• I would put the default config.json in a config-default directory.
• I would have the user put his config.json in a config-user directory (to be read-only for documentable after setup).
• I would prefer you to use the JSON::Hjson module for reading and writing the configuration files to minimize human error when modifying the config file.
• The default operation for generating the pages within a section is not clear since I can't see the new look, but it should be an alpha sort on the first visible title within each section.
• I would ensure there is some way to allow the user to generate a default config file with his own sections and one or more skeleton files. One HUGE advantage of Hjson is the ability to embed comments.
• It would be helpful to show the docs (written in Pod6) on-line as Markdown files for on-line rendering. Perhaps manually running Pod::To::Markdown on the when changed. Then reference those files in the Github IO pages.

[JJ]

Thanks, Tom. We'll look into it.

[antoniogamiz]

So the first two points says that we need two different directories. Once for default config and another for the user config. Where do you propose I create these directories? In the root directory? The user config dir does not have any problem, but the default should be inside resources dir because it needs to be used by the tests.

I like the idea about JSON::Hjson. In fact, I was having some troubles documenting the config file because I could not use comments. Thanks for the recommendation :).

[tbrowder]

I think having the default config info in the resources directory is okay, but, since it's default, it could be copied to a new dir on setup, and deleted upon clean, could it not?

My concern was that it's not so obvious where the default config is. But I guess I could live with it as is.

In like manner, I would have the user-config dir created on setup it it doesn't exist. And possibly just copy the default json into it at the same time.

[tbrowder]

Currently "Documentable" is not providing the config.json file, and possibly some other resources. I suggest, at least for Linux, we look for another solution instead of the wget and curl which rely on "external" resources. One possibility:

Use the "resources" directory and the META6.json so the resources get installed along with oher components. In addition, use the "hooks" directory to provide Perl executables to install the resources in a well-known directory like "/usr/share/raku/documentable/resources" (or, for a non-root user, in, say, the "$HOME/.raku/docmental/resources" directory). When "docmentable setup" is run it would copy the default config.json into the "config-local" directory, and other assets into the local doc repo in the appropriate directory. The user could, optionally, create a "config-user" directory for customizing the confg to his own requirements.

I will try to create a PR to demo this when I get the time (as well as clean up the text in this stream of consciousness).

[JJ]

El mar., 17 sept. 2019 a las 19:13, Tom Browder (<notifications@github.com>) escribió:

Currently "Documentable" is not providing the config.json file, and possibly some other resources. I suggest, at least for Linux, we look for another solution instead of the wget and curl which rely on "external" resources.

Actually, in the case of the docs we are providing it via the repo itself. But you are right, this is less than awesome. I will try to create a PR to demo this when I get the time (as well as

clean up the text in this stream of consciousness).

Thanks!

[tbrowder]

After some success, and then a set back, I stepped back and started with a clean slate to try to see the big picture. In an empty directory I executed:

$ git clone https://github.com/perl6/Documentable.git
$ cd D*
$ cp -rp . ../orig.Docucumentable
$ zef install --force-install .
$ cp -rp . ../orig.Documentable-after-install
$ ~/.perl6/bin/documentable setup
$ cp -rp . ../orig.Documentable-after-install-after-setup
$ cd ..; mkdir orig.doc-test-repo; cd orig.doc-test-repo
$ ~/.perl6/bin/setup

After all that I was able to see the different states and their directory structures. And that has helped me to see better how to proceed. Some fresh conclusions:

1. Testing Documentable is complicated by a directory structure not quite like a clean repo would have after the setup. Documentable may need a more complicated test structure to ensure we test what is actually needed, especially if it is to be used by a site outside our doc site. I am a strong believer in test-driven development, but, in this case, I think I will concentrate on getting the installation working such that I can take an independent doc repo and get it working before I look at more complete testing.

2. The desired added structure for a virgin doc repo should be duplicated in Documentable's repo, perhaps something like this:

assets/ html/ highlights/ template/ config-default/ config-user/

plus, of course, all the other directories in our doc model.

The only added directory that would be special would be the config-user directory which wouldn't be touched by setup but it would be used by documentable if it exists.

[JJ]

There's the mini-doc repo to that kind of things. You can improve it adding more test cases...

[antoniogamiz]

Hi, I'm still alive! Sorry for not being active lately. I'm trying to setup my new internet connection (there are several problems I hope to resolve this week). I have also started a new course at the University so I'm kind of buddy. Thanks for your work @tbrowder, I will implement it ASAP. El sáb., 21 sept. 2019 10:20, Juan Julián Merelo Guervós < notifications@github.com> escribió:

…

There's the mini-doc repo to that kind of things. You can improve it adding more test cases... — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#37>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFPOARZVS47BXJWNUJQCMX3QKXKLZANCNFSM4ITAPMPQ> .

[tbrowder]

@JJ and @antoniogamiz, don't listen to my babbling too much, but I am still learning @antoniogamiz's strategy which looks better the more I look at it. The thoughts I put down yesterday are mostly wrongish, but I have more hope for today's direction. I think the main problem is the disconnect between the Documentable file tree and the using doc repo layout.

I plan to try a slightly different tack today back toward a slightly different layout.

Good luck to both of you for the new school year!

[antoniogamiz]

Thanks! What do you mean by "Documentable file tree and the using doc repo layout"? Documentable only needs a root dir and the name of the subdirectories to work. By default, it looks for "Language Types Native Programs", but it can be configured using the CLI. El sáb., 21 sept. 2019 13:29, Tom Browder <notifications@github.com> escribió:

…

@JJ <https://github.com/JJ> and @antoniogamiz <https://github.com/antoniogamiz>, don't listen to my babbling too much, but I am still learning @antoniogamiz <https://github.com/antoniogamiz>'s strategy which looks better the more I look at it. The thoughts I put down yesterday are mostly wrongish, but I have more hope for today's direction. I think the main problem is the disconnect between the Documentable file tree and the using doc repo layout. I plan to try a slightly different tack today back toward a slightly different layout. Good luck to both of you for the new school year! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#37>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFPOAR75HK5MVRTPZIDPMPTQKYASBANCNFSM4ITAPMPQ> .

[tbrowder]

You are correct, but I'm trying to clearly distinguish between installation of the Document module versus using the installed documentable in a doc repo--mainly to help my understanding of the process, if nothing else.

[antoniogamiz]

Use the "resources" directory and the META6.json so the resources get installed along with oher components. In addition, use the "hooks" directory to provide Perl executables to install the resources in a well-known directory like "/usr/share/raku/documentable/resources" (or, for a non-root user, in, say, the "$HOME/.raku/docmental/resources" directory). When "docmentable setup" is run it would copy the default config.json into the "config-local" directory, and other assets into the local doc repo in the appropriate directory. The user could, optionally, create a "config-user" directory for customizing the confg to his own requirements.

The problem with using resources directory is that we need to list every file in META6.json. I think this is LTA because there is a considerable amount of files which should be listed. Another option would be to make a zip (which can be used in windows too) and include that zip in META6.json. What do you think?

For now, as for the configuration file, I will store it in a directory called .documentable in order to follow the common convention (.vscode, .circleci, etc.).

[tbrowder]

After much work trying to implement my suggestions, I think you may be at least partially correct. I have experimented with the Build.pm6 but it cannot do all it needs to do with the current state of zef.

The only problem I see with the zipped archive is how it should be part of the build process and not a separate dev step. I have reverted to putting file names back into the META6.json and don't think that is too burdensome.

At the moment I am trying to clearly separate the files needed for testing versus the files needed for setup: quite a chore.

[tbrowder]

I'm closing this for now.

[antoniogamiz]

I will try to address these problems in the near future.

[antoniogamiz]

When akiym/JSON-Hjson#3 is resolved, I will include it.

[antoniogamiz]

I have seen that YAML supports comments by default, so maybe we should that instead of JSON or HSON.

[JJ]

The module above has been released anew, check it out.

[antoniogamiz]

I know, I propelled that release. But as YAML has a shorter syntax and has comments support by default, I think it's a better option.

[JJ]

Your call. As long as you have to use an external module, I guess YAML is as good as HJSON or even JSON.