iiasa / message_doc

MESSAGEix-GLOBIOM documentation
https://docs.messageix.org/global/
8 stars 18 forks source link

Clean-up to address Sphinx warnings #44

Closed khaeru closed 4 years ago

khaeru commented 4 years ago

Although the build succeeds, it generates numerous warnings. This PR addresses these:

  1. Correct malformed reStructuredText:
    • Title underlines match length of titles.
    • Trailing space inside :math: role.
  2. Fix erroneous citations and references.
  3. Deduplicate repeated labels:
    • tab-globff → tab-global-ff-res, tab-ag-emissions-globiom-fao.
    • spatial → globiom-spatial, spatial.
  4. Adds extra.rst, including fifteen (15) additional files in that were omitted from the build. For each of these, it must be decided to (a) remove, (b) keep and include in a certain place/order.

    Refer to https://message.iiasa.ac.at/projects/global/en/cleanup/extra.html, which contains these built files.

    • [x] annex/message/deleted_imports_and_exports: → moved to _extra
    • [x] climate/magicc/climate_indicators: → moved to _extra
    • [x] commodities/ (4 files): superseded by energy/enduse/industrial → delete
    • [x] econ: empty → delete
    • [x] emissions/gains/ (2 files): empty → delete
    • [x] emissions/message/f_gases: → moved to _extra
    • [x] emissions/message/ghgs: superseded by emissions/message/index → delete
    • [x] energy/resource: trimmed duplicate content, remaining moved to _extra
    • [x] glossary: added to main toctree, copyedited.
    • [x] land_use/globiom: empty → delete
    • [x] land_use/linkage: → moved to _extra
    • [x] message: superseded by energy/index → delete
    • [x] overview/model_concept: empty → delete
    • [x] overview/policy/cancun: empty → delete
    • [x] overview/policy/index: handled in #48 by @volker-krey, thanks!

It also:

volker-krey commented 4 years ago

Unintentionally pushed directly to upstream (iiasa) instead of creating a PR, but changes are straight forward and URLs were all tested.

khaeru commented 4 years ago

@volker-krey thanks for jumping in with that fix.

Last time I raised this, we didn't know what we wanted to do with the files marked above with a "?".

To get this merged, I will make a new section for "backup" or "unused" content, move them there, and make a note in the README.

volker-krey commented 4 years ago

Let me have a look at the the files marked with "?", but adding a section "backup"or "unused" sounds good for keeping those files visible in the repo while not showing up in the build. Wouldn't it also be possible to just keep the files where they are, but simply not link to them or does that have downsides that I don't see right now?

khaeru commented 4 years ago

Wouldn't it also be possible to just keep the files where they are, but simply not link to them or does that have downsides that I don't see right now?

The only downside is for ourselves: being confused why they're there but missing from the index.