search

canonical / maas.io

Site for maas.io
https://maas.io/
GNU Lesser General Public License v3.0
17 stars 42 forks source link

API docs in HTML is difficult to maintain #448

Closed sparkiegeek closed 1 year ago

sparkiegeek commented 4 years ago

Summary

As of https://github.com/canonical-web-and-design/maas.io/commit/d0066a894a18b831dc430bc880f3fa198e6b1302 API docs for MAAS are published from a HTML document in this repo.

The source material for those docs is docstrings in the MAAS codebase. A short description of the publishing pipeline is in https://paste.ubuntu.com/p/HphN7txwQb/

As per discussions, it would be easier if the MAAS team could go from step 2. to proposing Markdown changed to this repo and skipping out the mythical step 4.

Process

Attempt to update API docs from a MAAS version.

Current and expected result

Currently stuck at step 4 of https://paste.ubuntu.com/p/HphN7txwQb/.

Expected to be able to easily update docs

nottrobin commented 4 years ago

@sparkiegeek could you provide us with the latest version of the markdown output from step 2, so that we could work on creating a markdown version of the API docs page?

sparkiegeek commented 4 years ago

https://github.com/CanonicalLtd/maas-docs/blob/master/en/api.md

sparkiegeek commented 4 years ago

@nottrobin any progress here?

nottrobin commented 4 years ago

Afraid not. I think this should be scheduled in by the Maas squad - @lilyvidenova?

lilyvidenova commented 4 years ago

We thought this would be something you guys did @nottrobin? @cristinadresch could you help here?

nottrobin commented 4 years ago

I'm very happy to help, but I have so far failed to just get it done in my abundance of spare time, so I think it needs official scheduling.

SirSamTumless commented 4 years ago

@cristinadresch Could you let us know where to plan this.

lilyvidenova commented 4 years ago

@Caleb-Ellis assigning you here, @nottrobin will be available to help

nottrobin commented 4 years ago

Just FYI, this should follow the model of the Ubuntu kubernetes docs - as in, a markdown file that lives directly in the site repo, that the site will parse at serve-time:

https://github.com/canonical-web-and-design/ubuntu.com/blob/master/templates/kubernetes/docs/index.md

anthonydillon commented 4 years ago

The content is ported in this branch https://github.com/canonical-web-and-design/maas.io/pull/497 but not closing this issue as it was manual.

The steps to replicate the port:

  1. Obtain maas-api.rst from running make docs in MAAS core
  2. Remove all instances of ############################### in the rst file
  3. Install pandoc locally
  4. Run pan pandoc maas-api.rst --from rst --to html5 -s -o maas-api.html
  5. Find and replace all <summary>`` to <summary><code>
  6. s/``</summary>/</code></summary>/
  7. copy and paste the content between the main div in the templates/docs/api.html in maas.io code base.
sparkiegeek commented 3 years ago 
cat ../maas/api-docs.rst | sed -e'/###############################/d' | pandoc - --from rst --to html5 -s -o- | \
sed -e's@^  <summary>``@<summary><code>@;s@``</summary>@</code></summary>@' > templates/docs/maas-api.html
sparkiegeek commented 2 years ago

Ash nazg durbatulûk, ash nazg gimbatul, ash nazg thrakatulûk, agh burzum-ishi krimpatul.

cat ../maas/api-docs.rst | pandoc - --from rst --to html5 -s --shift-heading-level-by=1 -o templates/docs/maas-api.html

Then manually compare (e.g. meld templates/docs/{,maas-}api.html) next steps would be something like extracting <body /> and put it in <div class="l-docs-row row">