이것은 저의 마지막 글과 최종 보고서입니다. GSoC 2020의 일부로서 Dhall documentation generator

초기 문제

다르어는 상대적으로 새로운 언어이다.Dhall 패키지를 사용하는 방법을 보는 유일한 방법은 코드를 수동으로 검사하고 주석을 읽는 것입니다.Dhall Prelude는 이런 방법의 좋은 예로 제목에 주석을 추가했다. 예를 들어 this 예시와 같다.일부 패키지는 심지어 주석이 없기 때문에 이 패키지를 어떻게 사용하는지 알기 위해 실제 코드를 읽어야 합니다.

주요 공헌

제 GSoC 프로젝트의 일부로서 저는 dhall-docs 을 구축했습니다. 이것은 Dhall 패키지를 받아들이고 패키지의 모든 파일에 대해 정적 분석을 통해 HTML 문서를 생성합니다.이 도구에는 다음과 같은 기능이 있습니다.

모든 파일을 포함하는 폴더를 가져와 제목을 추출하고 HTML을 출력하여 문서(#1845를 표시합니다

.

UI/UX(#1848,#1895

향상을 위해 간단한 CSS와 JS를 사용하여 HTML을 구현

인덱스의dhall files 부분은 모든 파일의 형식을 포함합니다(소스 코드에서 추출)#1898

생성된 HTML(#1899

의 전용 섹션에서 추출하여 단언 표현식을 표시합니다.

태그 해석기를 사용하기 전에 들여쓰기를 올바르게 처리하기 위한 주석 문법 규범을 생성했습니다(#1929

JTD(정의로 이동) 기능이 있는 소스 코드는 다음 위치에 표시됩니다.

표현식 가져오기(#1959

귀속명(#1966

Lambda 매개변수 이름#1982

레코드(텍스트 및 유형) 필드 이름(#1991

상기 명세서의 PRS에서 개술한 작업 외에 나는 dhall-docs 저장소의 dhall-haskell 패키지에 대해 다음과 같은 기술 개선을 진행했다.

코드 변경golden tests

을 통해 생성된 문서를 보존하도록 설정 추가#1899

은dhall-kubernetes의 금 테스트 설정에 사용된Prelude, dhall-docs 과test demo package 문서를 생성합니다.

dhall-haskell 저장소에 작성된 모든 PRS 목록을 찾을 수 있습니다 here
...업스트림 변경 사항 Dhall Language Standard:

레코드 필드 레이블에 추가 테스트 추가#1013

및 dhall-docs 패키지 관리 방법과 관련된 변경 사항(#1026, #1053

저는 스승님뿐만 아니라 댓글을 통해 많은 지역사회와 공개적이고 적극적으로 dhall-docs 행위와 관련된 일을 토론했습니다.가장 관련된 직위는 다음과 같다.

The first discussion about the dhall-docs goals and my introduction to the community

The announcement of the first release of dhall-docs

대화에서 내 메시지를 보고 싶으면dhall-lang.org,gohere
...이 절이 끝날 때, 비록 이것은 나의 프로젝트와 직접적인 관계가 없지만, 나는 지역 사회 연결 기간의 작은 문제를 토론함으로써 기존의 코드 라이브러리를 익혔다.나는 이미 댓글에서 이야기했다.
모든 소스 코드를 찾을 수 있습니다 here.우리는 이미 dhall-docs GitHub release 및 Hackage 에 발표했지만, 그것은 모든 기능을 포함하지 않는다.우리는 this release PR on the standard 패키지의 다른 버전을 발표하기 위해 dhall-haskell 합병되기를 기다리고 있습니다. dhall-docs 을 포함합니다.

미정 작업

만약 우리가 이미 완성한 일을 나의 제안과 비교한다면, 우리에게 부족한 것은 다음과 같다.

나타나는 원본 코드에 문법을 돋보이게 한다.우리는 처음부터 그것을 가지고 있었지만, 정의에 점프를 추가하려면 원본 코드를 보여주는 방식을 바꿔야 한다.JTD

의 전류fragments 기능과 함께 추가할 수 있습니다.

스톱을 입력합니다.우리는 하나WIP PR가 있는데, 나는 완성할 수 없다. 비록 그것의 상태는 매우 좋지만.

원본 코드 중 다른 곳의 주석을 읽습니다.이때 dhall-docs 파일의 헤더 주석만 지원하고 기록 필드, lambda, 함수 형식 파라미터 등 다른 위치에 대한 지원을 추가하는 것이 좋습니다.이 작업의 가장 어려운 부분은 공백을 정확하게 보존하는 것이지만we're making progress.

가져오기와 관련된 표현식의 정의로 이동합니다.현재 클릭한 표현식이 상대적으로 원격으로 가져오는 경우 다른 URL로 이동합니다.그러나 (./Import.dhall).field.deep 같은 일은 아직 처리하지 않았으니 매우 유용할 것이다.dhall 패키지에서 흔히 볼 수 있는 모델은 패키지의 모든 파일을 포함하는 package.dhall 파일을 사용하는 것이다. 위의 예시를 사용하면 내비게이션 가능성을 크게 높일 수 있다

이 기능들이 완성되지 않아서 나는 결코 괴로워하지 않는다.나는 JTD에 필요한 더 많은 공백 dhall-docs 을 보존하기 위해 Dhall 해상도에 약간의 개선을 했다. 이것은 예상보다 더 많은 시간을 들였다.가장 좋은 부분은 그곳에서 완성된 작업은 dhall format 명령상의 long-standing 문제를 복구하는 데도 사용할 수 있다는 것이다.어쨌든 이것은 매우 좋은 균형이다😄

화면 캡처 및 데모 패키지

다음은 생성된 문서 외관의 화면 캡처입니다.이것은 샘플 패키지dhall-haskell에서 실행된 dhall-docs CI/CD 결과에서 얻은 것으로, 작업이 최신 dhall-lang 업데이트를 제출하지 않았기 때문에 거의 모든 관련 가져오기 링크가 끊어졌습니다 dhall-docsDhall Prelude 패키지 인덱스:
Prelude/Bool/package.dhall 본질적으로 Prelude 내의 하위 패키지입니다. Prelude/Bool 내의 모든 파일을 다시 내보냅니다.
Prelude/Bool/fold 추출된 헤더를 태그, 단언, 정의 기능으로 표시하기 때문에 매우 완전합니다.

test demo package 레코드 필드에서 정의로 이동하는 가장 좋은 예는 "내포된 레이블이 있는 정의로 이동"입니다.

상대 가져오기 링크를 사용하여 동일한 패키지의 다른 표현식으로 이동할 수 있습니다.

마지막 생각

나는 GSoC팀으로부터 제의가 받아들여졌다고 메일을 받은 후에 정말 방에서 소리를 질렀던 것을 기억한다. 그때부터 많은 일들이 바뀌었다.그 순간부터 독일인들은 그가 지난 4개월 동안 배운 모든 것이 Haskell뿐만 아니라 개원 프로젝트에 관한 것이라고 믿지 않을 것이다.
개원 프로젝트의 가장 중요한 부분은 그 지역사회이다. 지역사회가 없고 프로젝트는 코드일 뿐이다.만약 당신이 진정한 열정이 없거나 그 중에서 어떤 자금도 얻지 못한다면 적극적이고 주동적이기 어렵다.구글의 이 프로젝트의 제안은 많은 프로젝트가 진행 중인 문제를 완성하고 신흥 도구 (예를 들어 Dhall) 에 새로운 문제를 제공하는 데 도움을 주었다.
처음 개원에 기여하는 것은 복잡할 수도 있지만, 일단 익숙해지면 정말 간단해진다. 당신은 많은 이익을 얻을 수 있다.

커뮤니티 구성원 되기

좋아하는 생태계의 성장을 돕습니다

기술과 비기술적인 측면에서 당신의 직업 생활을 개선

투고 dhall-haskell 전에 저의 Haskell은 대학 프로젝트에서 왔습니다.나는 이 프로젝트들이 ok-ish Haskell을 사용했다고 말할 수 있다. 나는 정말 자랑스럽다.나는 아무도 나의 코드를 심사하지 않는다. 나는 많은 것을 개선할 수 있다고 생각한다. 나는 어떤 비교점도 없다.
내가 복제 dhall-haskell 를 하고 어떤 파일을 열었을 때, 나는 이것이 나에게 있어서 모두 새롭다는 것을 알았다.언어 잡주 같은 일은 완전히 미지의 것이다.다음을 포함합니다.

{-# LANGUAGE OverloadedStrings #-}

l :: Data.Text.Text
l = "string literal"

처음에는 (aString와 어떻게 호환되는지 곤혹스러웠습니다.지금은 정말 쉽지만!
편지함, 응용 프로그램, 리스트를 정확하게 사용합니다(심지어 제 것을 실현합니다!)제가 오래전에 하고 싶었던 일이에요. 창고에서 PRS를 몇 번 하고 나니 자연스럽기 시작했어요.
나는 불법 상태를 나타낼 수 없도록 더 많은 데이터 형식을 만들기 시작했다. 이것은 내가 두려워하는 일이다. (내가 낡은 프로젝트에서 Data.Text.Text와Maybe렌즈를 과도하게 남용했기 때문이다. 비록 나는 []에서 자주 사용하지 않았지만, 나는 나를 놀라게 하는 것을 멈추었다.
나는 더 많은 것을 쓸 수 있지만, 나는 이 문장이 지금보다 더 길기를 원하지 않는다.
비록 이것은 내가 GSoC 프로젝트에서 일한 끝이지만, 나는 내가 머지않아 계속 공헌할 것이라고 믿는다

감사를 드리다

저의 스승님Gabriel,Simon과Philip:저에게 이 기회를 주셔서 감사합니다. 그곳에 계셔서 감사합니다. 전체 프로젝트에 대한 인내심에 감사드립니다.dhall-docs 개발에 대한 당신의 지도에 감사드리며, 저에게 당신의 개원 방면의 경험을 알려 주십시오.
Dhall 커뮤니티에 대해 저의 개방적인 질문에 적극적으로 응답해 주십시오.
Haskell.org 주최 프로젝트에 가서 어떤 프로젝트 선택을 할지 결정하도록 도와주세요😉
마지막으로 가장 중요하지 않은 점은 구글이 GSoC 프로젝트를 제공해 줘서 고맙다는 것이다.이것은 정말 당신의 직업 생활을 개선하고 개원 지역사회가 더욱 크고 강해지는 것을 돕는 좋은 방법이다.
감사합니다.❤️