diff --git a/docs/development/documentation.rst b/docs/development/documentation.rst index 1773ac7ed5..afe3ff8710 100644 --- a/docs/development/documentation.rst +++ b/docs/development/documentation.rst @@ -88,4 +88,19 @@ Further Guidance - The sphinx warnings are OK as long as the build occurs, errors will cause the crash the build. - Make sure all your internal API references start with ``tidy3d.`` -- In notebooks, always have absolute links, otherwise the links will break when the user downloads them. \ No newline at end of file +- In notebooks, always have absolute links, otherwise the links will break when the user downloads them. + + +Writing Documentation +^^^^^^^^^^^^^^^^^^^^^^^^ + +... raw:: + + Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python Developer’s Guide for documenting which you may follow: + # with overline, for parts + * with overline, for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs + diff --git a/docs/development/index.rst b/docs/development/index.rst index 0ea13f358e..0fb06ca6c4 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -9,7 +9,6 @@ Welecome to the ``tidy3d`` developers guide! :maxdepth: 2 introduction/index - project_structure installation usage documentation @@ -17,7 +16,6 @@ Welecome to the ``tidy3d`` developers guide! release/index .. include:: /development/introduction/index.rst -.. include:: /development/project_structure.rst .. include:: /development/installation.rst .. include:: /development/usage.rst .. include:: /development/documentation.rst diff --git a/docs/development/installation.rst b/docs/development/installation.rst index 78d9eeba16..0e611595d2 100644 --- a/docs/development/installation.rst +++ b/docs/development/installation.rst @@ -1,5 +1,5 @@ -Installation -============== +Development Environment Installation +===================================== The Fast Lane -------------- diff --git a/docs/development/introduction/code_quality.rst b/docs/development/introduction/code_quality_principles.rst similarity index 98% rename from docs/development/introduction/code_quality.rst rename to docs/development/introduction/code_quality_principles.rst index 9e7dd60a32..296a960284 100644 --- a/docs/development/introduction/code_quality.rst +++ b/docs/development/introduction/code_quality_principles.rst @@ -1,5 +1,5 @@ -Code Quality ------------- +Code Quality Principles +------------------------ When writing a code snippet, remember the saying: "code is read more than written". We want to maintain our code maintainable, readable and high quality. diff --git a/docs/development/introduction/index.rst b/docs/development/introduction/index.rst index 66eccda462..e6c351e1f6 100644 --- a/docs/development/introduction/index.rst +++ b/docs/development/introduction/index.rst @@ -16,7 +16,11 @@ This page hopefully will get you started to develop Tidy3D. understanding_virutal_environments understanding_poetry + code_quality_principles + project_structure .. include:: /development/introduction/understanding_virutal_environments.rst -.. include:: /development/introduction/understanding_poetry.rst \ No newline at end of file +.. include:: /development/introduction/understanding_poetry.rst +.. include:: /development/introduction/code_quality_principles.rst +.. include:: /development/introduction/project_structure.rst \ No newline at end of file diff --git a/docs/development/project_structure.rst b/docs/development/introduction/project_structure.rst similarity index 97% rename from docs/development/project_structure.rst rename to docs/development/introduction/project_structure.rst index 736ef5512c..a902933a58 100644 --- a/docs/development/project_structure.rst +++ b/docs/development/introduction/project_structure.rst @@ -1,5 +1,5 @@ -Project Structure -================= +``tidy3d`` Project Structure +============================== As of ``tidy3d>=2.6``, the frontend has been restructured to improve the development cycle. The project directories follow the following structure, which is derived from some recommended `Python project architecture guides `_. This is a handy structure because many tools, such as ``sphinx``, integrate quite well with this type of project layout. diff --git a/docs/development/release/documentation.rst b/docs/development/release/documentation.rst index 41d016b6ef..1f73fb01fc 100644 --- a/docs/development/release/documentation.rst +++ b/docs/development/release/documentation.rst @@ -23,18 +23,4 @@ Hot Fix & Submodule Updates To make a “hot fix” (eg fix a typo, add a notebook, update the release FAQ), just update the ``latest`` branch in ``tidy3d`` repo. This should automatically sync to `tidy3d-docs`, and trigger a docs rebuild. **However, we should avoid this as this will cause the ``develop`` and ``latest branches`` to diverge.** Ideally, these hot fixes could wait until the next pre/post-release to be propagated through. -NOTE: To avoid conflicts, ideally we should only update ``latest`` by merging ``develop`` in it, or at the very least we should make sure changes are propagated to both branches. - -Writing Documentation -^^^^^^^^^^^^^^^^^^^^^^^^ - -... raw:: - - Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python Developer’s Guide for documenting which you may follow: - # with overline, for parts - * with overline, for chapters - = for sections - - for subsections - ^ for subsubsections - " for paragraphs - +NOTE: To avoid conflicts, ideally we should only update ``latest`` by merging ``develop`` in it, or at the very least we should make sure changes are propagated to both branches. \ No newline at end of file