fixing toctree, removing unneeded files

Signed-off-by: vsoch <vsoch@users.noreply.github.com>
oras-project · Jul 13, 2022 · 89dead0 · 89dead0
1 parent 51c395e
commit 89dead0
Show file tree

Hide file tree

Showing 6 changed files with 24 additions and 85 deletions.
diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html
diff --git a/docs/_templates/sidebar.html b/docs/_templates/sidebar.html
diff --git a/docs/conf.py b/docs/conf.py
@@ -97,14 +97,6 @@
 extensions.append("sphinx_material")
 html_theme_path = sphinx_material.html_theme_path()
 html_context = sphinx_material.get_html_context()
-
-# Add sidebar navigation to all pags
-html_context["sidebar_nav"] = {
-    "Getting Started": "https://oras.land/client_libraries/1_python/",
-    "Developer Guide": "getting_started/index.html",
-    "Contributing": "contributing.html",
-    "License": "about/license.html",
-}
 html_theme = "sphinx_material"
 html_css_files = ["custom.css"]
 

diff --git a/docs/getting_started/developer-guide.md b/docs/getting_started/developer-guide.md
@@ -1,4 +1,4 @@
-# Developer Guide {#getting_started-developer-guide}
+# Developer Guide
 
 This developer guide includes more complex interactions like
 contributing registry entries and building containers. If you haven\'t
@@ -13,14 +13,9 @@ The documentation is provided in the `docs` folder of the repository,
 and generally most content that you might want to add is under
 `getting_started`. For ease of contribution, files that are likely to be
 updated by contributors (e.g., mostly everything but the module generated files)
- are written in markdown. This means that we cannot use [toctre](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents), which relies on rst (restructured syntax) and the workaround is
- to define the table of contents links (globally) in `conf.py` and then to
-write them into `_templates/globaltoc.html`. It's not as nice as using rst,
-but since Markdown is the chosen language for the oras community we support
-that and want to make it as easy as possible to contribute documentation.
-You shouldn't need to do much other than edit markdown files, and if you
-do need to change the table of contents (or something else advanced) please
-[open an issue](https://github.com/oras-project/oras-py/issues) and ask for help!
+ are written in markdown. If you need to use [toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) you should not use extra newlines or spaces (see index.md files for exampls).
+Markdown is the chosen language for the oras community, and this is why we chose to
+use it over restructured syntax - it makes it easier to contribute documentation.
 
 
 ### Install Dependencies and Build

diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -9,5 +9,8 @@ user guide (and more detailed examples) can be found here. If you have
 any questions or issues, please [let us
 know](https://github.com/oras-project/oras-py/issues)
 
-- [Installation](installation.md)
-- [Developer Guide](developer-guide.md)
+```{toctree}
+:maxdepth: 3
+installation
+developer-guide
+```
diff --git a/docs/index.md b/docs/index.md
@@ -35,3 +35,18 @@ developer, see the `getting-started`{.interpreted-text role="ref"} page
 hosted here. Would you like to request a feature or contribute?
 
 [Open an issue](https://github.com/oras-project/oras-py/issues).
+
+```{toctree}
+:maxdepth: 1
+Getting Started <https://oras.land/client_libraries/1_python/>
+getting_started/index.md
+contributing.md
+about/license
+```
+
+```{toctree}
+:caption: API
+:maxdepth: 1
+source/modules.rst
+```
+