https://pantsbuild.org/ logo
Join Slack
Powered by
Looks like we have some complications with the in-...
# development
h
Looks like we have some complications with the in-repo docs, when it comes to creating new pages.
One that is relatively easy to overcome is that a new page requires a category ID in its front matter. Our exported preexisting documents don't have that in their front matter, so there isn't an easy place to copy from, but you can list category IDs by curling against the relevant API endpoint, so far so good.
The bigger issue is that after that running the 
rdme
sync command works, and says it has created the page, but the page is not visible on the site
Neither in the navigation, nor by direct link using the slug, nor in search
The page exists at the API level (the API returns info for it, and I can DELETE it via the API), but is not visible in practice
Will look more this weekend or whenever, but just a heads-up
h
maybe we create a blank page directly in Readme.com first
h
That should work but is hardly a viable way forward. And this is supposed to work without that.
b
Ouch. I need to add a page too, so will be interested to hear how this is resolved.
h
Looks like it created it, but in 2.12!
And I definitely ran with 2.13 as the version
will dig further
OK, figured this out
To create a new doc you have to specify its category in the front matter
and the category IDs are different between versions
So naively fetching them gives the wrong category
But this also means that we can't leave the category ID in the front matter
we have to add it there temporarily for the initial document creation
and then remove it, because for example when we fork a new version of the docs, we'd have to replace all the category ids
We'll have to script this up
b
This is not the clarity we dreamed of.
h
No, but we never pitched Readme.com in-repo as bringing clarity! Chris and I have been saying it's an imperfect half-way state, and really we want something like Sphinx But the halfway state is dramatically better than what we had before. So much of my resentment towards docs has gone away hah
b
How close are we to sphinx?
h
I'd expect a week's worth of time. So: as soon as we can find a week vs other priorities for the project Imo, the main motivation for Sphinx should be unblocking a reorg of our docs, that we have more nesting in docs. Otherwise I think the status quo is "good enough". The warts like creating a page are infrequent or not enough of a big deal
☝️ 1
fyi @ancient-vegetable-10556
h
Yeah, there are multiple reasons to go to sphinx or similar, this is another one
3 Views
Open in Slack
PreviousNext
Powered by