pursuit
pursuit copied to clipboard
purescript
Use PURSUIT.md instead of README if it is present
I remember talking about this somewhere so apologies if it's a duplicate - I couldn't see one anywhere.
I suggest an easy quick-fix for this would be to remove sections in the markdown that start with the title Module documentation.
Often, I want to include different information on Pursuit. What about adding PURSUIT.md, and falling back to README.md with no Module Documentation section if it's missing?
What different information do you want to include? Is it just the "module documentation" part that would be different?
I think I'd rather we remove "module documentation" parts from READMEs entirely and stop checking markdown documentation into repositories, because this encourages people to read docs on GitHub.
I was thinking about that as an option too, but then I'd probably want to link to Pursuit in the README, so you'd end up with a recursive link on the Pursuit page for the module :smile: (of course we could eliminate that too).
I don't see that as a problem - I was assuming that most people would link to Pursuit in their readmes, probably using one of those badges like Travis has. Also, I'd rather just leave it there - I don't think it does any harm, and I want to keep this kind of fiddling to an absolute minimum.
Well, I'd like to include it as a sentence or something, unless people know what "pursuit" means it doesn't really shout "documentation here!".
True, that does sound sensible. Perhaps we could also start putting Pursuit URLs into the repository website field that GitHub provides.
My initial reaction was that having yet another file to manage would feel a bit redundant (even if we say that we fallback to README.md). As I think more about it, I think that having a separate PURSUIT.md wouldn't be much different than Python projects that have entire directories for sphinx to parse in addition to the inline documentation.
My only remaining concern (if I ever get to a point where I'm writing library documentation) would be how much overlap there might be in having both files (eg. maybe something that's in PURSUIT.md is worth repeating in README.rst).
As another idea, would it be worth having special comments that are parsed by pursuit? Something like:
<!-- Start Pursuit -->
# Introduction
This is a simple introduction.
<!-- End Pursuit -->
# Details
This is more detail that belongs in a README but not [Pursuit](pursuit.purescript.org).
I suspect there might be a less noisy way to denote what pursuit should and shouldn't parse. Another way, and I think perhaps it was hinted at before, would be to give a standard list of sections that would be parsed by Pursuit. Anything else would be left out. For instance, in the following:
- Introduction
- Quick Start
- Detailed Overview
- Module Documentation Introduction and Quick Start would be parsed, but Detailed Overview and Module Documentation would not.
To be clear, I'm totally for just having a PURSUIT.md if that accomplishes what we need in order for READMEs to be parsed correctly without a lot of effort. I was just tossing a couple of ideas out there that may or may not make sense in future iterations.
I still think it seems like a decent idea, although since we don't generate docs/ and provide links to them in the READMEs anymore it is less of an issue.
Thinking about this again I'm quite keen to implement it, since as it is at the moment, almost every package on Pursuit has a link that says 'docs are on Pursuit', which is a bit silly - clearly such a link should be in the GitHub readme, but not displayed on Pursuit. Another reason is that I'd like to reduce the extent to which Pursuit is tied to GitHub, and in particular the use of the GitHub API for rendering readmes is awkward: it means that Pursuit needs internet access and GitHub needs to be up for READMEs to be displayed, for instance, and it's very slow compared to having that information available immediately in the JSON.
Rather than calling it PURSUIT.md, though, what about docs/index.md? That's a more obvious name for it, and also opens the possibility of including more files inside the docs folder if people want documentation split into different files. It's just a little unfortunate that docs/ is the default destination for generated Markdown docs, which we wouldn't want to include.
To do this, I think we would want to start by doing the following inside the compiler:
- Include
docs/**.mdin the Pursuit JSON blob inpsc-publish - Change
psc-docsto output docs to a different folder by default, saygenerated-docs.
Perhaps a bit more drastic / offtopic, but I'd also be fine with getting rid of psc-docs - since Pursuit came into existence I haven't used it, since there's no need to publish the markdown docs now. Even when it did exist I would tend to read comments in the source files rather than looking at the generated markdown. It was just useful as a reference when multiple modules were bundled into one file, etc. but with a real search that is redundant.
I definitely agree that the "front page" should be part of the pursuit blob too! I was very surprised to find that wasn't the case when there was an issue pulling them from GitHub a while back.
psc-docs can also generate tags files for editors and I don't see it as much of a maintenance burden, so I'd like to keep it, I think. I've also found pulp docs --with-dependencies quite useful for when I'm travelling without internet; it's nice to not have to dig through bower_components to find the information you're after.
I've just realised that the docs/ folder isn't hardcoded in psc-docs anywhere, it's just pulp that writes to that folder by default.
I'd also be fine with getting rid of psc-docs
It's useful for working offline, and it uses the same code with minimal additional code needed to support Markdown, so I'd like to keep it. Also, it will probably be useful for generating docs during the package sets CI task.